publib.boulder.ibm.compublib.boulder.ibm.com/tividd/td/ibmds/sparent322/en_us/pdf/lparent.pdf ·...

IBM® SecureWay® DirectoryVersion 3.2.2 for Linux:Installation, Configuration, andAdministration Guide

��

NoteBefore using this information and the product it supports, read the general information under “Appendix C. Notices” onpage 147.

First Edition (November, 2001)

This edition applies to version 3, release 2.2, of The IBM SecureWay Directory and to all subsequent releases andmodifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2000, 2001. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . vii

Chapter 1. System Requirements . . . . 1For SecureWay Directory client: . . . . . . . . 1For SecureWay Directory server (including the client) 1SSL Global Security Kit: . . . . . . . . . . 1

Chapter 2. Getting Started . . . . . . . 3Installing the SecureWay Directory . . . . . . . 3Installing the Global Security Kit . . . . . . . 4

Installing GSKit from command line: . . . . . 5Removing GSKit . . . . . . . . . . . . 5

Installing DB2 . . . . . . . . . . . . . . 5Configuring the environment . . . . . . . . . 6Creating the database . . . . . . . . . . . 7

Configuration settings . . . . . . . . . . 8Configuring the SecureWay Directory server . . . . 8Tuning information . . . . . . . . . . . . 9

DB2 database tuning parameters. . . . . . . 9DB2 Parameters . . . . . . . . . . . . 12Tuning Examples . . . . . . . . . . . 18SecureWay Directory Tuning Information . . . 21

Starting and stopping the SecureWay Directory . . 22Populating the directory . . . . . . . . . . 22Using LDAP client applications. . . . . . . . 22

Directory Management Tool . . . . . . . . 23Removing the SecureWay Directory . . . . . . 23

Chapter 3. Tasks . . . . . . . . . . 25Creating an administrator distinguished name andpassword . . . . . . . . . . . . . . . 25Creating or adding suffixes . . . . . . . . . 25Creating replica servers . . . . . . . . . . 25

Configuring replicas . . . . . . . . . . 26Populating the directory for a replica using theDB2 backup and restore . . . . . . . . . 29Listing replicas . . . . . . . . . . . . 30Adding replicas . . . . . . . . . . . . 30Removing replicas . . . . . . . . . . . 30Editing replicas . . . . . . . . . . . . 30Using peer-to-peer replication . . . . . . . 30Replica synchronization . . . . . . . . . 32

Working with DB2 databases . . . . . . . . 34Creating a database. . . . . . . . . . . 34Updating settings . . . . . . . . . . . 34Backing up a database . . . . . . . . . . 34Restoring a database . . . . . . . . . . 35Importing database entries . . . . . . . . 35Optimizing a database. . . . . . . . . . 35UTF-8 support . . . . . . . . . . . . 35Configuring the directory to use a database . . 38

Working with a change log . . . . . . . . . 38Change log configuration . . . . . . . . . 38Logging schema changes . . . . . . . . . 39Multiple database configuration . . . . . . 39

Change log access control . . . . . . . . 40Change log expiration of entries . . . . . . 40Change log schema . . . . . . . . . . . 40Working with Administration Utilities . . . . 43Unconfiguring changelog . . . . . . . . . 44

Working with referrals. . . . . . . . . . . 44Using the referral object class and the refattribute . . . . . . . . . . . . . . 44Associating servers with referrals . . . . . . 45Binding with a distributed namespace . . . . 46An example of distributing the namespacethrough referrals. . . . . . . . . . . . 46

Viewing error logs . . . . . . . . . . . . 48Understanding distinguished names (DNs) . . . . 49

Distinguished Name Syntax . . . . . . . . 49Pseudo DNs . . . . . . . . . . . . . 50

Chapter 4. Command line utilities . . . 53Client utilities . . . . . . . . . . . . . 53

Ldapdelete utility . . . . . . . . . . . 53Ldapmodify utility . . . . . . . . . . . 54Ldapadd utility . . . . . . . . . . . . 54Ldapmodrdn utility . . . . . . . . . . 54Ldapsearch utility . . . . . . . . . . . 54

Server utilities . . . . . . . . . . . . . 54Ldif utility. . . . . . . . . . . . . . 55Ldif2db utility . . . . . . . . . . . . 56Bulkload utility . . . . . . . . . . . . 56Db2ldif utility . . . . . . . . . . . . 59

Chapter 5. Directory schema . . . . . 61Common schema support . . . . . . . . . 61The subschema entries. . . . . . . . . . . 61The IBMsubschema object class . . . . . . . . 62The IBMAttributeTypes attribute type . . . . . 62Schema file attribute types . . . . . . . . . 63Schema queries . . . . . . . . . . . . . 64Dynamic schema changes. . . . . . . . . . 64Disallowed schema changes . . . . . . . . . 65Schema checking . . . . . . . . . . . . 65Checking an entry against the schema . . . . . 66Access controls . . . . . . . . . . . . . 67Replication . . . . . . . . . . . . . . 67Netscape compatibility . . . . . . . . . . 67Dynamic schema . . . . . . . . . . . . 68Subclassing . . . . . . . . . . . . . . 70DEN schema support . . . . . . . . . . . 70

Generalized and UTC time . . . . . . . . 70

Chapter 6. IBM SecureWay DirectoryManagement Tool . . . . . . . . . . 73Starting and configuring . . . . . . . . . . 73

Starting the Directory Management Tool . . . . 73Configuring the Directory Management Tool . . 73

Working with servers . . . . . . . . . . . 74

© Copyright IBM Corp. 2000, 2001 iii

Connecting to a server. . . . . . . . . . 75Viewing server status . . . . . . . . . . 75Viewing server properties . . . . . . . . 76Adding a server . . . . . . . . . . . . 76Deleting a server . . . . . . . . . . . 77Using server administration . . . . . . . . 77

Using the toolbar . . . . . . . . . . . . 77

Chapter 7. Access Control Lists . . . . 81The Access Control Attribute Syntax . . . . . . 81AclEntry . . . . . . . . . . . . . . . 82

Subject . . . . . . . . . . . . . . . 82Pseudo DN . . . . . . . . . . . . . 83Rights . . . . . . . . . . . . . . . 83

EntryOwner . . . . . . . . . . . . . . 84Propagation . . . . . . . . . . . . . . 85Access Evaluation . . . . . . . . . . . . 85Defining the ACIs and Entry Owners . . . . . . 87Modifying the ACI and Entry Owner Values . . . 87Deleting the ACI/Entry Owner Values . . . . . 89Retrieving the ACI/Entry Owner Values. . . . . 89Working with Access Control Lists . . . . . . 89

Chapter 8. Secure Sockets Layer . . . 93Securing your Server with SSL . . . . . . . . 93Configuring the directory to use SSL . . . . . . 94Server Certificate from an External CertificateAuthority(CA) . . . . . . . . . . . . . 95Using a Self-Signed Server Certificate. . . . . . 96Setting up Your LDAP Client to Access IBMSecureWay Directory . . . . . . . . . . . 97Configuring Server Encryption Ciphers . . . . . 98Client Authentication . . . . . . . . . . . 98

Chapter 9. Working with attributes 101Adding an attribute . . . . . . . . . . . 101Editing an attribute . . . . . . . . . . . 102Deleting an attribute . . . . . . . . . . . 102Binary attributes . . . . . . . . . . . . 102

Chapter 10. Working with objectclasses . . . . . . . . . . . . . . 105Adding an object class . . . . . . . . . . 105Editing an object class . . . . . . . . . . 105Deleting an attribute . . . . . . . . . . . 106

Chapter 11. Viewing the log file. . . . 107

Chapter 12. Working with directoryentries . . . . . . . . . . . . . . 109Searching the directory tree for entries . . . . . 109

Simple search . . . . . . . . . . . . 109Advanced search . . . . . . . . . . . 109Editing a saved search . . . . . . . . . 111Deleting a saved search . . . . . . . . . 111

Adding an LDAP entry . . . . . . . . . . 111Adding an auxiliary object class . . . . . . . 112Editing an LDAP entry . . . . . . . . . . 112Groups and Roles . . . . . . . . . . . . 113

Groups . . . . . . . . . . . . . . 113Roles . . . . . . . . . . . . . . . 113

Changing group membership . . . . . . . . 114

Appendix A. Indexing rules . . . . . 115Indexing Rules Specifications for Attributes: . . . 115

Appendix B. IBM SecureWay DirectoryConfiguration Schema . . . . . . . 117Directory Information Tree (DIT) . . . . . . . 117

cn=Configuration . . . . . . . . . . . 117cn=Event Notification . . . . . . . . . 118cn=Front End . . . . . . . . . . . . 118cn=Kerberos . . . . . . . . . . . . . 118cn=Master Server . . . . . . . . . . . 119cn=Referral . . . . . . . . . . . . . 119cn=Schemas . . . . . . . . . . . . . 120cn=IBM SecureWay . . . . . . . . . . 120cn=RDBM Backends . . . . . . . . . . 121cn=Directory . . . . . . . . . . . . 121cn=Change Log . . . . . . . . . . . 122cn=LDCF Backends . . . . . . . . . . 122cn=SchemaDB . . . . . . . . . . . . 123cn=SSL . . . . . . . . . . . . . . 123cn=CRL . . . . . . . . . . . . . . 124cn=Transaction . . . . . . . . . . . . 124

Attributes . . . . . . . . . . . . . . 125cn . . . . . . . . . . . . . . . . 126ibm-slapdAdminDN . . . . . . . . . . 126ibm-slapdAdminPW . . . . . . . . . . 126ibm-slapdChangeLogMaxEntries . . . . . . 127ibm-slapdConcurrentRW . . . . . . . . 127ibm-slapdDbConnections . . . . . . . . 127ibm-slapdDbInstance . . . . . . . . . . 128ibm-slapdLocation. . . . . . . . . . . 128ibm-slapdDbName . . . . . . . . . . 128ibm-slapdDbUserID . . . . . . . . . . 129ibm-slapdDbUserPW . . . . . . . . . . 129ibm-slapdEnableEventNotification . . . . . 129ibm-slapdErrorLog . . . . . . . . . . 129ibm-slapdIncludeSchema . . . . . . . . 130ibm-slapdKrbAdminDN . . . . . . . . . 130ibm-slapdKrbEnable . . . . . . . . . . 131ibm-slapdKrbIdentityMap . . . . . . . . 131ibm-slapdKrbKeyTab . . . . . . . . . . 131ibm-slapdKrbRealm . . . . . . . . . . 132ibm-slapdLdapCrlHost . . . . . . . . . 132ibm-slapdLdapCrlPassword . . . . . . . 132ibm-slapdLdapCrlPort . . . . . . . . . 133ibm-slapdLdapCrlUser . . . . . . . . . 133ibm-slapdMasterDN . . . . . . . . . . 133ibm-slapdMasterPW . . . . . . . . . . 134ibm-slapdMasterReferral . . . . . . . . 134ibm-slapdMaxEventsPerConnection . . . . . 134ibm-slapdMaxEventsTotal . . . . . . . . 135ibm-slapdMaxNumOfTransactions . . . . . 135ibm-slapdMaxOpPerTransaction . . . . . . 135ibm-slapdMaxTimeLimitOfTransactions. . . . 135ibm-slapdPeerDN . . . . . . . . . . . 136ibm-slapdPeerPW . . . . . . . . . . . 136

iv IBM® SecureWay® Directory Version 3.2.2 for Linux: Installation, Configuration, and Administration Guide

ibm-slapdPlugin . . . . . . . . . . . 136ibm-slapdPort . . . . . . . . . . . . 137ibm-slapdPWEncryption. . . . . . . . . 138ibm-slapdReadOnly . . . . . . . . . . 138ibm-slapdReferral . . . . . . . . . . . 138ibm-slapdSchemaAdditions. . . . . . . . 138ibm-slapdSchemaCheck . . . . . . . . . 139ibm-slapdSecurePort . . . . . . . . . . 139ibm-slapdSecurity . . . . . . . . . . . 140ibm-slapdSetenv . . . . . . . . . . . 140ibm-slapdSizeLimit . . . . . . . . . . 140ibm-slapdSslAuth . . . . . . . . . . . 141ibm-slapdSslCertificate . . . . . . . . . 141ibm-slapdSslCipherSpecs . . . . . . . . 141ibm-slapdSslKeyDatabase . . . . . . . . 142ibm-slapdSslKeyDatabasePW . . . . . . . 142

ibm-slapdSuffix. . . . . . . . . . . . 143ibm-slapdSysLogLevel . . . . . . . . . 143ibm-slapdTimeLimit . . . . . . . . . . 143ibm-slapdTransactionEnable . . . . . . . 144ibm-slapdUseProcessIdPw . . . . . . . . 144objectClass . . . . . . . . . . . . . 144

Schema definitions that cannot be changed . . . 145

Appendix C. Notices . . . . . . . . 147Trademarks . . . . . . . . . . . . . . 148

Glossary . . . . . . . . . . . . . 149

Index . . . . . . . . . . . . . . . 155

Contents v

vi IBM® SecureWay® Directory Version 3.2.2 for Linux: Installation, Configuration, and Administration Guide

Preface

IBM SecureWay Directory is a Lightweight Directory Access Protocol (LDAP)directory that runs as a stand-alone daemon. It is based on a client/server modelthat provides client access to an LDAP server. IBM SecureWay Directory providesan easy way to maintain directory information in a central location for storage,updating, retrieval, and exchange.

IBM SecureWay Directory provides the following functions:v Interoperability with other LDAP clientsv Access controlv Secure Sockets Layer Communicationv Referralsv Certificate managementv Replicationv Simple Authentication and Security Layer (SASL)v Client and server plug-in supportv CRAM-MD5 authenticationv UserPassword encryptionv UTF-8 database support

In addition, IBM SecureWay Directory provides the Directory Management Tool, agraphical user interface that enables you to manage information stored in directoryservers. Use the tool to:v Connect to one or more directory servers through non-SSL connectionsv Display server properties and rebind to the serverv List, add, edit, and delete schema attributes and object classesv List, add, edit, and delete directory entriesv Modify directory entry access control lists (ACLs)v Search the directory tree

IBM SecureWay Directory provides Secure Sockets Layer (SSL) Version 3 support,for the directory client on Red Hat Version 7.1, SuSe Version 7.2, and Turbolinux6.5. SSL provides encryption of data and authentication using X.509v3 public-keycertificates. The IBM SecureWay Directory can be configured to run with orwithout SSL support. IBM SecureWay Directory also supports LDAP referrals,which redirect directory operations to another LDAP directory server. Replicationof the LDAP Directory is supported and allows for additional copies of thedirectory to be available for directory read operations, which might increaseperformance and reliability when accessing directory information.

© Copyright IBM Corp. 2000, 2001 vii

viii IBM® SecureWay® Directory Version 3.2.2 for Linux: Installation, Configuration, and Administration Guide

Chapter 1. System Requirements

To install the IBM SecureWay Directory, your computer must meet the followingminimum system requirements.

For SecureWay Directory client:See the client README file for the latest information on supported versions ofLinux. If you are using a text editor, open/usr/ldap/web/<lang>/readme/client.txt, or if you are using a Web browser,open /usr/ldap/web/<lang>/readme/client.htm.v Linux Operating System from Red Hat Version 7.1 or higher, SuSe Version 7.2 or

higher, or Turbolinux Version 6.5 or higher.v A minimum of 128 MB RAM (256 MB or more is strongly recommended)

For SecureWay Directory server (including the client)See the server README file for the latest information on supported versions ofLinux. If you are using a text editor, open/usr/ldap/web/<lang>/readme/server.txt, or if you are using a Web browser,open /usr/ldap/web/<lang>/readme/server.htm.

In addition to the client requirements, the server requires the following:v DB2® Universal Database for Linux - Personal, Workgroup, or Enterprise edition

- version 7.1 or later.

Notes:

1. DB2 Version 7.2 Personal edition is included with the IBM SecureWayDirectory.

2. If you already have DB2 installed, you need approximately 45 MB of diskspace. You need approximately 135 MB of disk space for both LDAP andDB2.

3. Disk space required for data storage is dependent upon the number and sizeof database entries. Disk space required for data storage is dependent uponthe number and size of database entries. You need to allow a minumum of80 MB for your database on Unix systems. Also allow approximately another4 MB of disk space in th /home directory to create the db2 instance. See thereadme file for any additional information on database requirements.

SSL Global Security Kit:Global Security Kit (GSKit) is an optional software package that is required only ifSecure Socket Layer (SSL) Security is required. To enable SSL you need to installGSKit Version 5.04.

The SecureWay Directory V3.2.2 alone does not provide the capability for SSLconnections from SecureWay Directory clients. You can add the SSL feature byinstalling the IBM GSKit package . The GSKit package includes SSL support andassociated RSA (4) technology.

GSKit 5.04 for Linux to be used with the SecureWay Directory consists of thefollowing rpm file:

© Copyright IBM Corp. 2000, 2001 1

ibm_gsk5bas–5.0–4.13-X.i386.rpman RPM install image that contains the Export GSKit Base Toolkit installimage.

Note: The SecureWay Directory server works without the GSKit installed. In thiscase it accepts only non-SSL connections from SecureWay Directory clients.Similarly, the SecureWay Directory client works without the GSKit installed.

2 IBM® SecureWay® Directory Version 3.2.2 for Linux: Installation, Configuration, and Administration Guide

Chapter 2. Getting Started

The following instructions tell you how to set up a basic SecureWay Directory. Youcan find more detailed information in subsequent sections of this documentation.

Installing the SecureWay Directory

Note: Before installing the IBM SecureWay Directory, you must remove anynon-IBM versions of LDAP that might have been installed previously. If youtry to install the IBM SecureWay Directory over an existing non-IBM versionof LDAP, such as OpenLDAP, the SecureWay Directory does not installcorrectly. If this occurs you must remove the IBM SecureWay Directory andthen reinstall it. See “Removing the SecureWay Directory” on page 23.

One method to determine if you have a previously installed version ofLDAP is to issue the following command to query the installed packages:rpm -qa | grep -i ldap

This command finds any installed applications containing the name ldap.This method works only if you have a version of LDAP that contains thestring ldap in its application names.

The IBM SecureWay Directory for Linux is shipped in the following packages:v ldap-server-3.2.2-1.i386.rpm (56-bit encryption)v ldap-client-3.2.2-1.i386.rpm (56-bit encryption)v ldap-serverd-3.2.2-1.i386.rpm (128-bit encryption)v ldap-clientd-3.2.2-1.i386.rpm (128-bit encryption)v ldap-msg-xxx-3.2.2-1.i386.rpm (Where xxx is language dependent.)v ldap-html-xxx-3.2.2-1.i386.rpm (Where xxx is language dependent.)

To install the IBM SecureWay Directory with no encryption, you must:

Note: For Turbolinux Version 6.5, during the install, the install tool (rpm) thinksthere is a dependency on the file libstdc++.so.2.9 and cannot find it eventhough a more recent version is on the system. To fix this problem specify--nodeps (dash dash nodeps) in the rpm input parameters. For example:rpm --nodeps -hiv ldap-client-3.2.2-1.i386.rpm

Specifying --nodeps bypasses dependency checking. It allows the code to beinstalled.

1. Install the client:rpm -hiv ldap-client-3.2.2-1.i386.rpm

2. Install the server:rpm -hiv ldap-server-3.2.2-1.i386.rpm

3. Verify that the packages have been installed correctly:rpm -qa | grep ldap

If the product has been successfully installed, the following is displayed:


ldap-client-3.2.2-1ldap-server-3.2.2-1

4. Install the language dependant messages or documents:rpm -hiv ldap-msg-xxx-3.2.2-1.i386.rpmrpm -hiv ldap-html-xxx-3.2.2-1.i386.rpm

After installing the messages, you need to set the following environmentvariables:export NLSPATH=/usr/share/i/8n/msg/%L/%Nexport LANG=xxxLC_ALL=xxx

where xxx is the language. For example, de_DE.

Note: The client package must be installed before the server package can beinstalled.

To install the IBM SecureWay Directory client with 56-bit encryption, you must:1. Install the client:

rpm -hiv ldap-client-3.2.2-1.i386.rpm


If the product has been successfully installed, the following is displayed:ldap-client-3.2.2-1

To install the IBM SecureWay Directory client with 128-bit encryption, you must:1. Install the client:

rpm -hiv ldap-clientd-3.2.2-1.i386.rpm


If the product has been successfully installed, the following is displayed:ldap-clientd-3.2.2-1

Installing the Global Security KitTo install a secure SecureWay Directory from the SecureWay Directory package,first install the client from the package. Then, install the GSKit on the client.

Notes:

1. To use SSL on Red Hat Version 7.0, you must set the LD_PRELOADenvironment variable to /usr/lib/libstdc++-libc6.1-1.so.2. This must be donebefore running SSL, or starting slapd or any LDAP client applications that useSSL.export LD_PRELOAD=/usr/lib/libstdc++-libc6.1–1.so.2

2. For Turbolinux Version 6.5, during the install, the install tool (rpm) thinks thereis a dependency on the file libstdc++.so.2.9 and cannot find it even though amore recent version is on the system. To fix this problem specify --nodeps(dash dash nodeps) in the rpm input parameters. For example:rpm --nodeps -hiv gsk5bas-5.0.-4.13.i386.rpm

Specifying --nodeps bypasses dependency checking. It allows the code to beinstalled.


Installing GSKit from command line:To install in the default location: /usr/local, issue the following command as root:rpm -hiv ibm_gsk5bas-5.0-4.13.i386.rpm

Removing GSKitTo remove the GSKit packages, issue the following command:rpm -evv <package_name>

where:

-evv Erase <package_name> and display debugging information.

Note: If no trace or debug information is desired, use just the -e flag.

<package_name>Name of the rpm package to be removed.

For example:rpm -evv ibm_gsk5bas-5.0-4.13.i386.rpm

See “Chapter 8. Secure Sockets Layer” on page 93 for information on Secure SocketsLayer (SSL).

Installing DB2The linuxdb2_72.tar contains all of the installation files for IBM UDB EnterpriseEdition version 7.2. You need to create a temporary directory to hold the DB2installation files. You also need approximately 325 MB of space to contain theinstallation, and 75 MB for the application itself. After the installation you canreclaim the installation space by removing the .tar file and the db2 directory. Toremove the db2 directory and the installation files issue the command:rm -rf db2

Note: You must have Korn Shell application installed on your operating systembefore you can install DB2.

If you are installing from a CD-ROM, unpack the file by typing the following fromthe command prompt:tar -xvf /mnt/cdrom/linuxdb2_72.tar

If the tar file is already on your system, unpack the file by typing the followingfrom the command prompt:tar -xvf linuxdb2_72.tar

This unpacks all of the files into a directory named db2.

Within the db2 directory, is the db2setup program. Change into the db2 directoryby entering the following command:cd db2

Note: Do not use the db2_install command to install DB2 because this commanddoes not transfer the required license information.

To install IBM UDB Enterprise Edition version 7.2, run the db2setup program byentering the following from the command line:

Chapter 2. Getting Started 5

./db2setup

You are presented with an installation menu.1. Move the highlight bar with the arrow keys to the second selection ″DB2 UDB

Enterprise Edition″.2. Press down the space bar to select it (an asterisk is displayed next to the

item).3. Use the tab key to move to [OK].4. Press Enter. The Create DB2 Services menu is displayed. Do not select

anything from this menu, (Do not create a DB2 Instance and Do not createthe Administration Server are selected by default).

5. Press Enter with the [OK] selection highlighted. You receive a warning TheDB2 instance is not created.

6. Press Enter with the [OK] selection highlighted. You receive a warningindicating The Administration server is not installed.

7. Press Enter with the [OK] selection highlighted. The DB2 setup utility screenis displayed listing all of the components to be installed (18 components).

8. Press Enter with the [Continue] selection highlighted. A warning screen isdisplayed indicating This is your last chance to stop.

9. Press Enter with the [OK] selection highlighted to start the install. A messageis displayed as each of the components is installed. After all the componentsare installed, a message Completed successfully is displayed.

10. Press Enter with the [OK] selection highlighted to close the message.11. Press Enter with the [OK] selection highlighted from the DB2 setup utility

screen. A Please Wait message is displayed Scanning your system forinformation.

12. Press Enter with the [Continue] selection highlighted. A warning messageindicating that The DB2 instance is not created is displayed.

13. Press Enter with the [OK] selection highlighted. A warning messageindicating that The Administration server is not installed is displayed.

14. Press Enter with the [OK] selection highlighted.15. Press Enter with the [OK] selection highlighted to exit the db2setup program.

For more information on installing DB2, see the DB2 Website athttp://www-4.ibm.com/software/data/db2/.

Configuring the environmentYou need to add DB2INSTANCE and LD_LIBRARY_PATH to your environment.The following examples assume that you are using the bash shell. If you use adifferent shell, substitute the appropriate .login or .profile for .bashrc.1. Log on as ’root’, or enter the command:

su -

2. Run the following commands to modify your environment:echo 'export DB2INSTANCE=ldapdb2' >>x/.bashrcecho 'export LD_LIBRARY_PATH=/usr/IBMdb2/V7.1/lib:/usr/ldap/lib:$LD_LIBRARY_PATH' >>x/.bashrc. x/.bashrc

Note: Ensure that you include the tilde character before /.bashrc in theprevious commands.


http://www-4.ibm.com/software/data/db2/

Creating the databaseIBM SecureWay Directory uses a DB2 database to store directory data. Use thefollowing steps to create that database on your system.1. Create a group named ’dbsysadm’ for the database administrators:

groupadd [-g <gid>] dbsysadm

Note: The groupadd command on some Linux distributions requires that thegroup ID number (gid) be specified using the ’-g <gid>’ syntax. Type cat/etc/group to find an available group ID number. RedHat automaticallyassigns the next available gid if the -g option is not specified.

2. Add users ’root’ and ’ldap’ to the dbsysadm group.a. Open /etc/group in your favorite editor.b. Add the users ″root,ldap″ to the last line

Note: There are no spaces in the syntax.dbsysadm:x:<gid>:root,ldap

orsed -e 's/|dbsysadm:.*:$/&root,ldap/g' /etc/group > group.tmpcp group.tmp /etc/grouprm group.tmp

3. Create a user account (ldapdb2) for the DB2 instance:useradd -g dbsysadm -m ldapdb2

4. Set the password for the user account (ldapdb2):passwd ldapdb2

Enter the new password when prompted. (You might want to record yourpassword for future reference.)

5. Create the DB2 Instance (ldapdb2):/usr/IBMdb2/V7.2/instance/db2icrt -u ldapdb2 ldapdb2

6. Create the DB2 database:su - ldapdb2

(Log in using password created in step 4.)db2startdf -kdb2 create db ldapdb2 on /home/ldapdb2 using codeset UTF-8 territory USexit

Notes:

a. The database requires at least 80 MB. By default it is created in the/home/ldapdb2 directory. If you do not have sufficient space on the /homefilesystem, create it now or select an alternate location where user ldapdb2has full access privileges. Substitute that path for /home/ldapdb2 in theprevious command.

b. You must configure the SecureWay Directory server before you can beginpopulating the database. See “Configuring the SecureWay Directory server”on page 8 for instructions on completing this task.


Configuration settingsThe following DB2 configuration settings must be made to ensure properoperations. This must be done for databases used by the slapd server, includingldapdb2 (the default backend database) and ldapclog (the changelog database, ifenabled).1. Log on as ldapdb2

su - ldapdb2

2. View current database configuration settings, issue from command line:db2 get db cfg for <databasename>

View current database manager configuration settings, issue from commandline:db2 get dbm cfg

3. Update the following database configuration settings withdb2 update db cfg for <databasename> using <parm><newvalue>

Table 1.

DB2 Parameter Minimum value allowed

APPLHEAPSZ 1280

PCKCACHESZ 360

For example:db2 update db cfg for ldapdb2 using applheapsz 1280

4. Restart DB2DB2STOPDB2START

Configuring the SecureWay Directory serverAfter creating the DB2 database, you must configure the SecureWay Directoryserver.

All configuration for the server is contained in the file /usr/ldap/etc/slapd32.conf.Most administration tasks involve editing this file.

The file uses LDIF-like format (see rfc2849, LDAP Data Interchange Format) todescribe entries in a directory tree rooted at the DN: ″cn=Configuration″ (seerfc2253, Distinguished Name and “Understanding distinguished names (DNs)” onpage 49 for additional information). Remember that the first line of each entry inan LDIF file must be the entry’s dn, and every entry must end with a blank line.1. Set the administrator password:

a. Open /usr/ldap/etc/slapd32.conf in your editor.b. Insert the password indicated in bold type into the first entry before ’cn:

Configuration’:dn: cn=Configurationobjectclass: topobjectclass: ibm-slapdTopibm-slapdAdminDn: cn=rootibm-slapdAdminPW: <password>cn: Configuration

2. Configure the DB2 codepage.You created the database using codeset UTF-8. The server is configured to usethat code page. You need not change anything. If you created the database


http://www.cis.ohio-state.edu/htbin/rfc/rfc2849.html

http://www.cis.ohio-state.edu/htbin/rfc/rfc2253.html

using a local code page, scroll down to the next entry and remove the lineindicated in bold type before ’cn: Front End’ or if you created the databaseusing a different code page modify that line to reflect the correct code pagenumber.dn: cn=Front End, cn=ConfigurationobjectClass: topobjectClass: ibm-slapdFrontEndibm-slapdSetenv: DB2CODEPAGE=1208cn: Front End

3. Configure the directory to use the database.You must tell the server to use the database that you created. Scroll down tothe last entry and insert the password indicated in bold type before ’cn:Directory’:dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdRdbmBackendibm-slapdDbInstance: ldapdb2ibm-slapdDbName: ldapdb2ibm-slapdDbUserId: ldapdb2ibm-slapdDbUserPW: <password>cn: Directory

where <password> is the password you set in step 4 of “Creating the database”on page 7.

4. Save the file.Attention: This file contains the IDs and passwords for both the directoryadministrator (superuser) and the database itself. Anyone with access to read orwrite this file can get administrator access to your directory. To protect thisinformation, ensure that only the owner (ldap) has read and write access andthat only members of the ldap group have read access to this file.chown ldap:ldap slapd32.confchmod 640 slapd32.conf

Tuning informationThe following information might inprove the performance of you SecureWayDirectory:

DB2 database tuning parametersThe default settings for your DB2(R) database are sufficient to accommodate mostdirectories. If you find that this is not sufficient for your directory, the followinginformation provides you with instructions to increase the parameter values. Keepin mind that some database configuration parameters are customized specificallyfor the SecureWay(R) Directory product, but you might need to tune others foryour specific hardware.

The tuning parameters described in this section are ones that might improveperformance. Tuning them might not always improve performance. In fact, tuningmight degrade the performance under a radically different environment. Theremight be other parameters not described in this section that might improve yourperformance. You can use the database monitor to find out. For more informationon DB2 tuning, see the DB2 documentation at http://www-4.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v7pubs.d2w/en_main.


http://www-4.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v7pubs.d2w/en_main


Tune only one parameter at a time. Ensure that you record the original value ofeach parameter that you want to change. If you see negative results, set theparameter back to its original value.

Note: If you have any trouble running the DB2 commands, check to ensure thefollowing:v The ID trying to run the DB2 commands is a user in the dbsysadm group.

Only users listed as database administrators can execute the DB2commands. This includes the DB2 instance owner (the default is ldapdb2)and root.

v DB2 environment variables have been established by running db2profile(if not, the db2 get and db2 update commands do not work). Script filedb2profile is located in the sqllib subdirectory under the instance owner’shome directory. If you need to tailor this file, follow the comments insidethe file to set your instance name, user paths, and default database name(the default path is /home/ldapdb2/sqllib/db2profile).

There are two types of database configuration parameters:v Database Manager Configuration Parametersv Database Configuration Parameters

Database Manager Configuration ParametersThese determine the system resources that affect all databases and applicationsusing DB2. Use the following command to view the database managerconfiguration.db2 get database manager configuration

Before making changes to the database parameters, check and record the currentsettings. To change or set the database manager configuration parameters, use thefollowing command:db2 update database manager configuration using <parameter><value>

Attention: Changing database manager configuration parameters affects all thedatabases in your system.v Change the value of the SHEAPTHRES parameter. This helps if you are using

fuzzy searches, search filters with boolean operators, and so forth. Use thedatabase monitor to see if your sort heap is exceeding its limit. Set it to a highervalue to see if there is any effect.

See Examples for an example of a database manager configuration file.

Database Configuration ParametersThese apply to a specific database and specify the amount of resources allocated tothat database.

Before making changes to the database parameters, check the current settings. Usethe following commands to view the database manager configuration and databaseconfiguration parameters.

Use the following command to view the database configuration parameters for aspecific database:db2 get database configuration for <database name>

If you want the server administration interface to create the default database foryou, the database name is LDAPDB2.


The database configuration parameters, BUFFPAGE and DBHEAP, can affectperformance. The default BUFFPAGE included with DB2 is 1000 (4KB) pages,which might not be big enough for a large database. You might need to allocatebetween 50-70% of the memory to buffpage. For example, for a machine with256MB RAM, set buffpage to 40000. You might need to use a single buffer pool forthis value to take effect.

If you increase the BUFFPAGE parameter, increase the DBHEAP size one for every30 increments in the BUFFPAGE. For example, for a machine with 256MB RAM,set dbheap to 2500.

To specify that you are using a single buffer pool, issue the command:db2 alter bufferpool ibmdefaultbp size -1

Note: Do not attempt to use more than one buffer pool unless you know how todo specialized tuning on DB2.

To increase the size of BUFFPAGE and DBHEAP issue the command:db2 update database configuration for ldapdb2 using <parameter><value>

For example, to increase BUFFPAGE to 20000 (and to make the necessary,corresponding change to DBHEAP), enter:db2 update database configuration for ldapdb2 using buffpage 20000 dbheap 1866

SORTHEAP and MAXLOCKS are two additional parameters that might helpimprove performance depending on your system.

See Examples for an example of a database configuration file.

Data organization and maintenanceAfter a large number of updates, you need to collect statistics about tables,columns, and indexes. This information needs to be put into system catalog tablesby using the runstat command.runstats on table <tablename> and indexes all

Note: The runstats command can also be invoked by the reorgchk utility.

Freeing up Disk Space: After a significant amount of update activity on adirectory, the database might occasionally need maintenance to free up unuseddisk space and to make the queries more efficient. Use the reorgchk utilityperiodically to identify DB2 tables that need to be reorganized.

reorgchk on table <tablename> (invokes runstats)reorgchk update statistics on table all (invokes runstats)reorgchk current statistics on table all (does not invoke runstats)

For example, the command db2 reorgchk on table all generates output such asthe following:Doing RUNSTATS ....

Table statistics:

F1: 100*OVERFLOW/CARD < 5F2: 100*TSIZE / ((FPAGES-1) * 4020) > 70F3: 100*NPAGES/FPAGES > 80

CREATOR NAME CARD OV NP FP TSIZE F1 F2 F3 REORG-------------------------------------------------------------------------------


SYSIBM SYSFUNCTIONS 112 0 9 9 37184 0 100 100 ---SYSIBM SYSINDEXAUTH 15 0 1 1 735 0 - 100 ---SYSIBM SYSINDEXES 70 46 3 8 28000 65 99 37 *-*SYSIBM SYSKEYCOLUSE 1 0 1 1 63 0 - 100 ---SYSIBM SYSPLAN 25 0 2 2 11200 0 100 100 ---SYSIBM SYSPLANAUTH 49 0 1 1 2254 0 - 100 ---

... etc ...

The *-* characters in the REORG column indicate that the table needs to bereorganized. You might need to reorganize all tables flagged by reorgchk. You cando this with the following commands:reorg table <fully-qualified-tablename>

for example:db2 reorg table SYSIBM.SYSINDEXES

or if the table is indexed:reorg table <fully-qualified-tablename> index <indexname>

DB2 ParametersTuning these DB2 parameters might improve the performance of the SecureWayDirectory server.

Buffer Pool Size (buffpage)Configuration type

Database

Parameter typeConfigurable

Default [range]

UNIX® 32-bit platforms1 000 [2 through 524 288]

UNIX 64-bit platforms1 000 [250 through 2 147 483 647]

OS/2® and Windows NT® platforms250 [2 through 524 288]

Unit of MeasurePages

When allocatedWhen the first application connects to the database

When freedWhen the last application disconnects from the database

Each database has at least one buffer pool (IBMDEFAULTBP, which is createdwhen the database is created), and can have more. All buffer pools reside in globalmemory, which is available to all applications using the database. The memory isallocated on the machine where the database is located. If the buffer pools arelarge enough to keep the required data in memory, less disk activity will occur.Conversely, if the buffer pools are not large enough, the overall performance of thedatabase can be severely curtailed and the database manager can becomeI/O-bound as a result of a high amount of disk activity (I/O) required to processthe data your application requires.


The buffpage parameter controls the size of a buffer pool when the CREATEBUFFERPOOL or ALTER BUFFERPOOL statement was run with NPAGES -1;otherwise, the buffpage parameter is ignored and the buffer pool is created withthe number of pages specified by the NPAGES parameter.

To determine whether the buffpage parameter is active for a buffer pool, do a:SELECT * from SYSCAT.BUFFERPOOLS.

Each buffer pool that has an NPAGES value of -1 uses buffpage.

There is a trade-off between the buffer pool size and the memory allocations ofother system users. Memory requirements of database servers are so important onmulti-user high transaction rate servers, that database servers and file orcommunication servers are often separated and reside on different machines.

If your queries access nicknames, consider increasing the buffer pool size when:v The optimizer decides that most or all operations are completed locally. When a

query is processed, the optimizer usually pushes down operations to the datasource where possible. As an example, a GROUP BY operator is usuallyevaluated at the data source. It is possible, however, that materializing the tableat DB2 and performing an operation locally is the least cost route. This situationcould occur if the DB2 server workstation is more powerful than the data sourceworkstation.

v Sort operations must be completed locally. Queries containing nicknames aresorted according to the DB2 collating sequence. If a data source does not havethe same collating sequence, all sort operations are performed locally.

All buffer pools are allocated when the first application connects to the database,or when the database is explicitly activated. As an application requests data out ofthe database, pages containing that data are transferred to one of the buffer poolsfrom disk. (Note that database data is stored in pages within the tables on thedisk.) Pages are not written back to disk until the page is changed and one of thefollowing occurs:v All applications disconnect from the databasev The database is explicitly deactivatedv The database quiesces (that is, all connected applications have committed)v Its space is required for another page that needs to be read into the buffer poolv A page cleaner is available (num_iocleaners) and is activated by the database

manager.

Recommendations:

v Instead of using the buffpage configuration parameter, you can use the CREATEBUFFERPOOL and ALTER BUFFERPOOL SQL statements to create and changebuffer pools and their sizes.

v The size of the buffer pool is used by the optimizer in determining access plans.You should consider rebinding applications (using the REBIND PACKAGEcommand) after changing this parameter.

v Because the sizes of all the buffer pools can have a major impact onperformance, you should consider the following factors to ensure that excessivepage swapping does not occur:– The amount of installed memory on your machine.– The memory required by other applications running concurrently with the

database manager on the same machine.


Page swapping results when there is not enough memory to hold the page thatis being accessed. The result is that the page is written (’swapped’)to temporarydisk storage to make room for the other page. When the page on the temporarydisk storage is needed, it is ’swapped back’ into memory.

v You might wish to allocate as much as 75% of the machine’s memory to thedatabase buffer pools when you have the following:– Multiple users– A machine used only as a database server– A large amount of repeated access to the same data and index pages– One database on the machine.

v For every buffer pool page allocated, some space is used in the database heapfor internal control structures. If the total size of the buffer pool (or buffer pools)is increased, you may also need to increase dbheap.

v If the data source collating sequence matches the DB2 collating sequence, ensurethat the server option collating_sequence is set to indicate so.

You can use the database system monitor to calculate the buffer pool hit ratio,which can help you tune your buffer pools.

For more information about this parameter, see the DB2 Administration Guide,Volume 3: Performance at http://www-4.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v7pubs.d2w/en_main

Database Heap (dbheap)Configuration type

Database


Default [range]

UNIX 1200 [32 through 524 288]

OS/2 and Windows NT Database server with local and remote clients600 [32 through 524 288]

OS/2 and Windows NT Database server with local clients300 [32 through 524 288]

Unit of MeasurePages (4 KB)

When allocatedWhen the first application connects to the database

When freedWhen the last application disconnects from the database

There is one database heap per database, and the database manager uses it onbehalf of all applications connected to the database. It contains control blockinformation for tables, indexes, table spaces, and buffer pools. It also containsspace for the log buffer (logbufsz), and the catalog cache (catalogcache_sz).Therefore, the size of the heap will be dependent on the number of control blocksstored in the heap at a given time. The control block information is kept in theheap until all applications disconnect from the database.





The minimum amount the database manager needs to get started is allocated atthe first connection. The data area is expanded as needed up to the maximumspecified by dbheap.

Recommendation: Increase this value when an application receives an errorindicating that there is not enough storage available in the database heap toprocess the statement.

You can use the database system monitor to track the highest amount of memorythat was used for the database heap.

For more information about this parameter, see the DB2 Administration Guide,Volume 3: Performance at http://www-4.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v7pubs.d2w/en_main.

Maximum Percent of Lock List Before Escalation (maxlocks)Configuration type

Database


Default [range]

UNIX 10 [1 through 100]

OS/2 and Windows NT platforms22 [10 through 100]

Unit of MeasurePercentage

Lock escalation is the process of replacing row locks with table locks, reducing thenumber of locks in the list. This parameter defines a percentage of the lock listheld by an application that must be filled before the database manager performsescalation. When the number of locks held by any one application reaches thispercentage of the total lock list size, lock escalation will occur for the locks held bythat application. Lock escalation also occurs if the lock list runs out of space.

The database manager determines which locks to escalate by looking through thelock list for the application and finding the table with the most row locks. If afterreplacing these with a single table lock, the maxlocks value is no longer exceeded,lock escalation will stop. If not, it will continue until the percentage of the lock listheld is below the value of maxlocks. The maxlocks parameter multiplied by themaxappls parameter cannot be less than 100.

Recommendation: When setting maxlocks, you should consider the size of thelock list (locklist):maxlocks =100 *(512 locks per application*32 bytes per lock*2)/(locklist *4096 bytes)

This sample formula allows any application to hold twice the average number oflocks.

You can increase maxlocks if few applications run concurrently because there arenot a lot of contention for the lock list space in this situation.





You can use the database system monitor to help you track and tune thisconfiguration parameter.

The control of lock escalation through this parameter is important to the optimizerbecause it uses this parameter to determine access paths. Consider rebindingapplications after changing this parameter.


Sort Heap Size (sortheap)Configuration type

Database


Default [range]256 [16 through 524 288]

Unit of MeasurePages (4 KB)

When allocatedAs needed to perform sorts

When freedWhen sorting is completed

This parameter defines the maximum number of private memory pages to be usedfor private sorts, or the maximum number of shared memory pages to be used forshared sorts. If the sort is a private sort, then this parameter affects agent privatememory. If the sort is a shared sort, then this parameter affects the database sharedmemory. Each sort has a separate sort heap that is allocated as needed, by thedatabase manager. This sort heap is the area where data is sorted. If directed bythe optimizer, a smaller sort heap than the one specified by this parameter isallocated using information provided by the optimizer.

Recommendations:

v Appropriate indexes can minimize the use of the sort heap.v Increase the size of this parameter when frequent large sorts are required.v When increasing the value of this parameter, you should examine whether the

sheapthres parameter in the database manager configuration file also needs to beadjusted.

v The sort heap size is used by the optimizer in determining access paths.Consider rebinding applications after changing this parameter.


Sort Heap Threshold (sheapthres)Configuration type

Database

Applies to








v Database server with local and remote clientsv Database server with local clientsv Partitioned database server with local and remote clientsv Satellite database server with local clients


Default [range]

UNIX 32-bit platforms20 000 [250 through 2 097 152]

UNIX 64-bit platforms20 000 [250 through 2 147 483 647]

OS/2 and Windows NT platforms20 000[250 through 2 097 152]

Unit of MeasurePages (4KB)

Private and shared sorts use memory from two different memory sources. The sizeof the shared sort memory area is statically predetermined at the time of the firstconnection to a database based on the value of sheapthres. The size of the privatesort memory area is unrestricted.

The sheapthres parameter is used differently for private and shared sorts:v For private sorts, this parameter is an instance-wide soft limit on the total

amount of memory that can be consumed by private sorts at any given time.When the total private-sort memory consumption for an instance reaches thislimit, the memory allocated for additional incoming private-sort requests will beconsiderably reduced.

v For shared sorts, this parameter is a database-wide hard limit on the totalamount of memory consumed by shared sorts at any given time. When this limitis reached, no further shared-sort memory requests will be allowed (until thetotal shared-sort memory consumption falls below the limit specified bysheapthres).

Examples of those operations that use the sort heap include: hash joins andoperations where the table is in memory.

Explicit definition of the threshold prevents the database manager from usingexcessive amounts of memory for large numbers of sorts.

Recommendations: Ideally, you should set this parameter to a reasonablemultiple of the largest sortheap parameter you have in your database managerinstance. This parameter should be at least two times the largest sortheap definedfor any database within the instance.

If you are doing private sorts and your system is not memory constrained, an idealvalue for this parameter can be calculated using the following steps:1. Calculate the typical sort heap usage for each database:

(typical number of concurrent agents running against the database)*(sortheap,as defined for that database)

2. Calculate the sum of the above results, which provides the total sort heap thatcould be used under typical circumstances for all databases within the instance.


You can use the database system monitor to track the sort activity.


Tuning ExamplesThe following are suggestions of what your configuration files might look like.

Database Manager ConfigurationDatabase Manager Configuration

Node type = Database Server with local and remote clients

Database manager configuration release level = 0x0900

CPU speed (millisec/instruction) (CPUSPEED) = 1.099539e-06

Max number of concurrently active databases (NUMDB) = 8Data Links support (DATALINKS) = NOFederated Database System Support (FEDERATED) = NOTransaction processor monitor name (TP_MON_NAME) =

Default charge-back account (DFT_ACCOUNT_STR) =

Java Development Kit 1.1 installation path (JDK11_PATH) =

Diagnostic error capture level (DIAGLEVEL) = 3Diagnostic data directory path (DIAGPATH) = /export/home/ldapdb2/sqllib/db2dump

Default database monitor switchesBuffer pool (DFT_MON_BUFPOOL) = OFFLock (DFT_MON_LOCK) = OFFSort (DFT_MON_SORT) = OFFStatement (DFT_MON_STMT) = OFFTable (DFT_MON_TABLE) = OFFUnit of work (DFT_MON_UOW) = OFF

SYSADM group name (SYSADM_GROUP) = DBSYSADMSYSCTRL group name (SYSCTRL_GROUP) =SYSMAINT group name (SYSMAINT_GROUP) =

Database manager authentication (AUTHENTICATION) = SERVERCataloging allowed without authority (CATALOG_NOAUTH) = NOTrust all clients (TRUST_ALLCLNTS) = YESTrusted client authentication (TRUST_CLNTAUTH) = CLIENT

Default database path (DFTDBPATH) = /export/home/ldapdb2

Database monitor heap size (4KB) (MON_HEAP_SZ) = 56UDF shared memory set size (4KB) (UDF_MEM_SZ) = 256Java Virtual Machine heap size (4KB) (JAVA_HEAP_SZ) = 512Audit buffer size (4KB) (AUDIT_BUF_SZ) = 0

Backup buffer default size (4KB) (BACKBUFSZ) = 1024Restore buffer default size (4KB) (RESTBUFSZ) = 1024

Sort heap threshold (4KB) (SHEAPTHRES) = 20000

Directory cache support (DIR_CACHE) = YES

Application support layer heap size (4KB) (ASLHEAPSZ) = 15Max requester I/O block size (bytes) (RQRIOBLK) = 32767Query heap size (4KB) (QUERY_HEAP_SZ) = 1000DRDA services heap size (4KB) (DRDA_HEAP_SZ) = 128





Priority of agents (AGENTPRI) = SYSTEMMax number of existing agents (MAXAGENTS) = 200Agent pool size (NUM_POOLAGENTS) = 16 (calculated)Initial number of agents in pool (NUM_INITAGENTS) = 0Max number of coordinating agents (MAX_COORDAGENTS) = MAXAGENTSMax no. of concurrent coordinating agents (MAXCAGENTS) = MAX_COORDAGENTS

Keep DARI process (KEEPDARI) = YESMax number of DARI processes (MAXDARI) = MAX_COORDAGENTSInitialize DARI process with JVM (INITDARI_JVM) = NOInitial number of fenced DARI process (NUM_INITDARIS) = 0

Index re-creation time (INDEXREC) = RESTART

Transaction manager database name (TM_DATABASE) = 1ST_CONNTransaction resync interval (sec) (RESYNC_INTERVAL) = 180

SPM name (SPM_NAME) =SPM log size (SPM_LOG_FILE_SZ) = 256SPM resync agent limit (SPM_MAX_RESYNC) = 20SPM log path (SPM_LOG_PATH) =

TCP/IP Service name (SVCENAME) =APPC Transaction program name (TPNAME) =IPX/SPX File server name (FILESERVER) =IPX/SPX DB2 server object name (OBJECTNAME) =IPX/SPX Socket number (IPX_SOCKET) = 879E

Discovery mode (DISCOVER) = SEARCHDiscovery communication protocols (DISCOVER_COMM) = TCPIPDiscover server instance (DISCOVER_INST) = ENABLE

Directory services type (DIR_TYPE) = NONEDirectory path name (DIR_PATH_NAME) = /.:/subsys/database/Directory object name (DIR_OBJ_NAME) =Routing information object name (ROUTE_OBJ_NAME) =Default client comm. protocols (DFT_CLIENT_COMM) =

Maximum query degree of parallelism (MAX_QUERYDEGREE) = ANYEnable intra-partition parallelism (INTRA_PARALLEL) = NO

No. of int. communication buffers(4KB)(FCM_NUM_BUFFERS) = 1024Number of FCM request blocks (FCM_NUM_RQB) = 512Number of FCM connection entries (FCM_NUM_CONNECT) = (FCM_NUM_RQB * 0.75)Number of FCM message anchors (FCM_NUM_ANCHORS) = (FCM_NUM_RQB * 0.75)

Database ConfigurationDatabase Configuration for Database ldapdb2

Database configuration release level = 0x0900Database release level = 0x0900

Database territory = en_USDatabase code page = 819Database code set = ISO8859-1Database country code = 1

Directory object name (DIR_OBJ_NAME) =Discovery support for this database (DISCOVER_DB) = ENABLE

Default query optimization class (DFT_QUERYOPT) = 5Degree of parallelism (DFT_DEGREE) = 1Continue upon arithmetic exceptions (DFT_SQLMATHWARN) = NONumber of frequent values retained (NUM_FREQVALUES) = 10Number of quantiles retained (NUM_QUANTILES) = 20


Backup pending = NO

Database is consistent = YESRollforward pending = NORestore pending = NO

Multi-page file allocation enabled = NO

Log retain for recovery status = NOUser exit for logging status = NO

Data Links Token Expiry Interval (sec) (DL_EXPINT) = 60Data Links Number of Copies (DL_NUM_COPIES) = 1Data Links Time after Drop (days) (DL_TIME_DROP) = 1Data Links Token in Uppercase (DL_UPPER) = NOData Links Token Algorithm (DL_TOKEN) = MAC0

Database heap (4KB) (DBHEAP) = 10200Catalog cache size (4KB) (CATALOGCACHE_SZ) = 64Log buffer size (4KB) (LOGBUFSZ) = 8Utilities heap size (4KB) (UTIL_HEAP_SZ) = 5000Buffer pool size (4KB) (BUFFPAGE) = 256000Extended storage segments size (4KB) (ESTORE_SEG_SZ) = 16000Number of extended storage segments (NUM_ESTORE_SEGS) = 0Max storage for lock list (4KB) (LOCKLIST) = 100

Max appl. control heap size (4KB) (APP_CTL_HEAP_SZ) = 128

Sort list heap (4KB) (SORTHEAP) = 2500SQL statement heap (4KB) (STMTHEAP) = 2048Default application heap (4KB) (APPLHEAPSZ) = 2048Package cache size (4KB) (PCKCACHESZ) = 360Statistics heap size (4KB) (STAT_HEAP_SZ) = 4384

Interval for checking deadlock (ms) (DLCHKTIME) = 10000Percent. of lock lists per application (MAXLOCKS) = 100Lock timeout (sec) (LOCKTIMEOUT) = -1

Changed pages threshold (CHNGPGS_THRESH) = 60Number of asynchronous page cleaners (NUM_IOCLEANERS) = 1Number of I/O servers (NUM_IOSERVERS) = 6Index sort flag (INDEXSORT) = YESSequential detect flag (SEQDETECT) = YESDefault prefetch size (4KB) (DFT_PREFETCH_SZ) = 192

Default number of containers = 1Default tablespace extentsize (4KB) (DFT_EXTENT_SZ) = 32

Max number of active applications (MAXAPPLS) = 40Average number of active applications (AVG_APPLS) = 1Max DB files open per application (MAXFILOP) = 64

Log file size (4KB) (LOGFILSIZ) = 4000Number of primary log files (LOGPRIMARY) = 3Number of secondary log files (LOGSECOND) = 2Changed path to log files (NEWLOGPATH) =Path to log files = /export/home/ldapdb2/ldapdb2/NODE0000/SQL00001/SQLOGDIR/First active log file =

Group commit count (MINCOMMIT) = 1Percent log file reclaimed before soft chckpt (SOFTMAX) = 100Log retain for recovery enabled (LOGRETAIN) = OFFUser exit for logging enabled (USEREXIT) = OFF

Auto restart enabled (AUTORESTART) = ONIndex re-creation time (INDEXREC) = SYSTEM (RESTART)


Default number of loadrec sessions (DFT_LOADREC_SES) = 1Number of database backups to retain (NUM_DB_BACKUPS) = 12Recovery history retention (days) (REC_HIS_RETENTN) = 366

ADSM management class (ADSM_MGMTCLASS) =ADSM node name (ADSM_NODENAME) =ADSM owner (ADSM_OWNER) =ADSM password (ADSM_PASSWORD) =

See the SecureWay Directory Tuning Guide for additional tuning information.flie:/usr/ldap/web/<language>/config/tuning.pdf

SecureWay Directory Tuning Information

Enabling concurrent read and writeBy default, the concurrent read write is disabled. To enable,set LDAP_CONCURRENTRW=TRUE

Note: In earlier versions of the SecureWay Directory (versions 3.1.5 and earlier) thevalues for LDAP_CONCURRENTRW were ON and OFF.

Attention: Occasionally, you might get stale data because of simultaneous readand write. Use this environment variable only if your application permits it.

Tuning LDAP cacheThe following actions might improve the performance of your SecureWayDirectory server:

Increase the entry cache size: The effectiveness of your LDAP cache depends onyour workload. If your workload makes multiple requests for the same entrywithin a short period of time, a larger cache size might help. By default, the entrycache size is 1000 (meaning it will cache 1000 entries).

To set the size to a different value, set RDBM_CACHE_SIZE to that value.set RDBM_CACHE_SIZE=5000

Filter cache is always ¼ of the entry cache and cannot be tuned separately.

Disable the access control cache: If the clients bind as the LDAP administrator,you might improve performance by turning off the access control cache from thedefault value of YES.set ACLCACHE=NO

Note: If your application binds to the LDAP server as the LDAP administrator(which frequently is the case) the access control cache is not used.

Increase the size of the ACLCACHE: If clients bind as individual users, do notturn the access control cache off. You can change its size by settingACLCACHESIZE (default is RDBM_CACHE_SIZE.) For example:set ACLCACHESIZE=5000

See the SecureWay Directory Tuning Guide for additional tuning information.flie:/usr/ldap/web/<language>/config/tuning.pdf


Starting and stopping the SecureWay DirectoryYou have minimally configured the server. Start it now to verify that theconfiguration is successful.1. Start the server (it takes longer to start the first time, because it must build all

the DB2 tables):slapd

2. Verify that the server is running:ps -ef | grep slapd

3. Stop the server:kill -9 ′cat /etc/slapd.pid′

Populating the directoryAlthough the server runs, it does not contain any data. To add data you must:v Define a suffix (or naming context), which specifies the root entry of the data

hosted by your server.v Add data to the directory.

Defining the suffix is always performed by editing the /usr/ldap/etc/slapd32.conffile. You can add data in numerous ways. This example imports an LDIF filecontaining sample data rooted at the suffix ’o=ibm,c=us’.1. Define the suffix:

a. Open /usr/ldap/etc/slapd32.conf in your editor.b. Verify that the predefined suffixes are in the line indicated by bold type in

the last entry before ’cn: Directory’:dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration...ibm-slapdDbUserPW: ******

ibm-slapdSuffix: o=ibm,c=uscn: Directory

c. Save the file.

See “Creating or adding suffixes” on page 25 for additional information.2. Import the sample data:

ldif2db -i /usr/ldap/examples/sample.ldif

Using LDAP client applicationsBecause your server is running and populated, you can test the client applications.1. Start the server:

slapd

2. Perform a command line search:v List everyone named Bob:

ldapsearch -b o=ibm,c=us 'cn=bob*'

v List only the titles of everyone named Garcia:ldapsearch -b o=ibm,c=us sn=garcia title

v List the telephone numbers of everyone in the Home Entertainment division:ldapsearch -b 'ou=Home Entertainment,ou=Austin,o=IBM,c=US' -s one objectclass=person \telephonenumber

v List all the members of the bowling team:ldapsearch -b o=ibm,c=us 'cn=bowling*' member


The IBM SecureWay Directory includes the standard command line clients:v ldapaddv ldapdeletev ldapmodifyv ldapmodrdnv ldapsearch

See the Client SDK Programming Reference for more information about using theLDAP clients.

Directory Management ToolThe IBM SecureWay Directory also includes a GUI client, the DirectoryManagement Tool.

Note: For the Directory Management Tool to work on the Linux systems, the kornshell (ksh) must be installed with the operating system.

If you have an X display:1. Start the server:

slapd

2. Start the Directory Management Tool:dmt

Use the Directory Management Tool Helps for information on using the tool.

Removing the SecureWay DirectoryIf you need to remove the SecureWay Directory, ensure that the server is stoppedand issue the following commands.

Note: If the SecureWay Directory server is installed, you must remove the serverbefore you remove the client (the reverse order of the installation).

rpm -ev ldap-server-3.2.2-1rpm -ev ldap-client-3.2.2-1


Chapter 3. Tasks

The following tasks can be performed by the directory administrator:

Creating an administrator distinguished name and passwordYou can create an administrator name and an administrator password by addingthe following entry to the slapd32.conf file:cn=Configurationibm-slapdAdminDN: <admindn>ibm-slapdAdminPW: <adminpassword>

See “Understanding distinguished names (DNs)” on page 49 for more informationabout distinguished names.

Creating or adding suffixesA suffix is a DN that identifies the top entry in a locally held directory hierarchy.Because of the relative naming scheme used in LDAP, this DN is also the suffix ofevery other entry within that directory hierarchy. A directory server can havemultiple suffixes, each identifying a locally held directory hierarchy, for example,o=ibm,c=us.

Note: The specific entry that matches the suffix must be added to the directory.

Entries to be added to the directory must have a suffix that matches the DN value,such as ’ou=Marketing,o=ibm,c=us’. If a query contains a suffix that does notmatch any suffix configured for the local database, the query is referred to theLDAP server that is identified by the default referral. If no LDAP default referral isspecified, an Object does not exist result is returned.

To create a suffix, add the following line ibm-slapdSuffix: <suffixname> to theslapd32.conf file stanza:DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configurationibm-slapdDbName: <databasename>ibm-slapdUserID: <username>ibm-slapdDbUserPW: <password>ibm-slapdDbInstance: <username>

Note: To delete a suffix, remove the line from the slapd32.conf file. To modify asuffix, edit the line in the slapd32.conf file.

Creating replica serversReplication is a technique used by directories to help improve performance,reliability, or both. The replication process keeps multiple directories synchronized.

There are several benefits realized through replication. The largest benefit isproviding a means of faster searches. Instead of having all search requests directedat a single server, the search requests can be spread among several differentservers. This might improve the response time for the request completion.


Through replication, a change made to one directory is propagated to one or moreadditional directories. In effect, a change to one directory shows up on multipledifferent directories. The IBM SecureWay Directory supports a master-slavereplication model. There are two types of directories: masters and replicas. TheSecureWay Directory refers to the master as the master server. The replicas arereferred to as replica servers.

Table 2. Master-replica server definitions

Master The master server contains the master directory information from whereupdates are propagated to the replicas. All changes are made and occur onthe master server, and the master is responsible for propagating thesechanges to the replicas (slaves).

Replica An additional server that contains a directory replica. The replicas must beexact copies of the master. The replica provides a backup to the masterserver. Even if the master server crashes, or is unreadable, the replica canstill fulfill search requests and provide access to the data.

Only one master server is allowed. Replicas cannot serve as masters to otherreplicas. You can request some types of updates on a replica server, but the updateis actually forwarded to the master server and made there. The master server thensends the update to the replicas. Until the master has completed replication of theupdate, the change is not reflected on the replica server where it was originallyrequested.

If you are no longer using a replica, you should remove its definition from themaster server. Leaving the definition causes the server to queue up all updates andmight use unnecessary directory space. Also, the master server continues trying tocontact the missing replica to retry sending the data.

Configuring replicas

Note: When you are configuring a replica server, ensure that you set the masterDN to an id that is not the same as the admin DN on the replica server . Ifthese DN ids are the same the replica servers can become unsynchronizedwith the master server. This causes errors on the master and causes the dataon the servers to be inconsistent.

The main concern is to prevent any updates to the directory while the data isbeing added to the master. There are several different ways to configure yourmaster and replica. Two methods are presented in the following.

Simple configurationThe simple configuration has fewer steps than the other method presented, but itcan be slower for large directories and can be used only when the master directoryis initially loaded. Use the “General configuration” on page 28 method when youare adding a replica to a master that is already loaded with data.1. Configure your master server and replicas as normal, unreplicated LDAP

servers.2. Configure a master server. For each replica server, the master server needs to

know:v The common name of the replica. This can be any name, but it must be

unique. It is recommended that you use the host name of the replica.v The host name of the replica.v The port number that is used by the replica server.


v The update interval in seconds. The update interval does not have to beconsistent from one replica to the next.

v The master DN that is used by the master server to communicate with thereplica.

v The password that the replica uses to communicate with the master server. Itcan be any value. However, make sure that the replica is configured with thesame password.

This information must be added to the directory on the master.a. Use an LDIF file to add a replica object to a master server’s directory. See

the following example for a file named myreplica.ldif (the information inbold type is needed when you configure the replica server).dn: cn=myreplica,cn=localhostcn: myreplicaobjectClass: replicaObjectobjectClass: topreplicaHost: myreplica.mycompany.comreplicaBindDn: cn=masterreplicaCredentials: master2passreplicaPort: 389replicaBindMethod: SimplereplicaUseSSL: FALSEreplicaUpdateTimeInterval: 0

b. Bind as the admin DN by issuing the following command:ldapadd -D cn=admin -w admin2pass -c -d -f myreplica.ldif

The advantage of this method is that the replica can be added without havingto stop and restart the master.

3. Configure each replica to be a replica server. You must tell each replica themaster DN and password as defined in step 2, indicated by bold type in thefollowing example. You also must specify the host name of the master, alsoindicated in bold type. Add the following object to the slapd32.conf file. Ensurethat a single blank line appears before and after this object.dn: cn=Master Server,cn=Configurationobjectclass: topobjectclass: ibm-slapdReplicationcn: Master Serveribm-slapdMasterPW: masterpass2ibm-slapdMasterDN: cn=mymasteribm-slapdMasterReferral: ldap://mymaster.mycompany.com

Note: Remove this object from the file, if the server is no longer treated as areplica.

4. Make sure that each replica server has the same suffixes defined as the master.Also make sure that each replica server has the same object class and attributedefinitions as the master server. (In other words, they must have identicalschema files.)

5. Restart all of your SecureWay Directory servers (master and replicas) to makesure that any changes to their configurations are activated.

6. You can enter data onto the master using the command line utilities for loadingdata, ldapadd (recommended), or ldif2db. When the data is loaded onto themaster, the master begins replicating it to all of the replica servers. When thedirectory load is complete, the replication stops, potentially leaving some dataunreplicated on the master.

7. Restart the master server after the data has completed loading on the master.This causes the master to finish replicating the data onto all of the replicas.

Chapter 3. Tasks 27

It is also very IMPORTANT that you restart the master server after you haveadded entries and before defining any additional replicas, or the master andnew replica can become out-of-synchronization.It is not necessary to restart he master server, if you use ldapadd to add entries.

Your SecureWay Directory configuration is ready for use. You do not need to waituntil all of the data has finished replicating onto your replica servers before usingthe SecureWay Directory. However, not all data will be present on your replicaservers until the process is complete, so your searches might return incomplete ormissing data.

Note: The critical things to keep in mind in the preceding steps are:v Make sure that all of the replicas are defined to the master server before

loading any data onto the master. If a replica is not defined, then the datawill not be queued for replication for that server.

v Make sure that each replica configuration (suffixes, and so on) is correctbefore starting it.

v If you have replication enabled, caution is advised when adding entries tothe master server. To get the additions to the replicas, you need to restartthe master server after adding the entries.

General configurationThe general configuration is used when you need to add a new replica server afterthe master server has had data loaded onto it. It can also be used to reload dataonto a replica that becomes out of synchronization with the master.

If this is a new replica, skip to step 5:1. Remove the replica definition from the master server.2. Shut down the replica server.3. Configure your replica as a normal, unreplicated LDAP server.4. Define the replica on the master server. See step 2 of “Simple configuration”

on page 26. This step causes the master server to begin queuing any updatesfor replication for any new replica servers.

5. Stop all updates on the master and stop the master server.6. Back up the directory using db2ldif.7. You can restart the master server.8. Make sure that the replica server has the same suffixes as the master server,

and that the /etc/v3.system.oc and /etc/v3.system.at files and any includedfiles are identical to the master server. DO NOT define the replica server as areplica at this time. The directory on the replica might become damaged if thereplica server contacts the master server before having its directory loaded.This is because the master might send updates that depend upon data that isnot yet loaded. If your directory becomes damaged, or you suspect that itmight be damaged, begin the configuration again with step 1.

9. Load the replica server using ldif2db or bulkload. You do not have to restartthe server before this step.

10. Define the replica as a replica server and specify the host name, DN, andpassword for the master server. See step 2 of “Simple configuration” onpage 26.

11. Restart the replica server. Any updates from the master that have been queuedup since the directory backup was taken will begin to be propagated. It mighttake a few minutes before the updates begin to appear.


Notes:

1. It is possible that a few updates occurred to the master server between the timethis new replica was defined to it and the time that the master’s directory wasmade read-only. Some messages might be displayed about modifications thatfail to propagate the replica because the modification was already made. Thesecan be ignored.

2. If the replica server is NOT defined on the master server before marking themaster as read-only and backing up the directory, then you will not be able todefine the replica to the master without making the directory read-write. Youwill lose any updates between the time you make the Directory read-write anddefine the replica to the master.

Populating the directory for a replica using the DB2 backupand restore

DB2 backup and restore provide an alternate way of creating a replica that is fasterthan using db2ldif and ldifdb2 or bulkload, especially with large directories.

There are two ways to use DB2 utilities to populate, or re-synchronize, thedirectory for a replica. If you already have a replica, you can copy its directory andleave the master server running. You can also copy the directory of the masterserver.

To copy a replica:1. Verify that the replica to be copied is current with the master server.2. Configure the master server to use the replica to be added.3. Stop the directory server on the replica to be copied.4. Do not stop the directory server on the master server. The changes will

accumulate for the replica that was stopped and for the new replica. Themaster server will report errors contacting the new replica as well as the onethat was stopped.

5. Back up the directory on the existing replica using the following commands:su - ldapdb2db2 backup database ldapdb2 to /a/big/filesystem/backup

Note: Specify a file system with enough free space for the backup. Give onlythe path name. DB2 names the backup files based on a timestamp.

6. After the backup is complete, start the directory server on the replica that wascopied. The master server begins sending the replica any changes that arepending. Changes for the new replica are accumulated.

7. Create the directory for the new replica by running the following commands onthe host of the new replica:su - ldapdb2db2 restore database ldapdb2 from /a/big/filesystem/backup replace existing

Use the same file system name used for the backup.8. Start the directory server for the new replica. The master server sends changes

made while the directory was being backed up and restored.

To copy a master:1. Configure the master to use the replica to be added.2. Stop the directory server on the master. No updates will occur until it is

restarted.

Chapter 3. Tasks 29

3. Back up the directory on the master server using the following commands:su - ldapdb2db2 backup database ldapdb2 to /a/big/filesystem/backup

Specify a file system with enough free space for the backup. Give only the pathname. DB2 will name the backup files based on a timestamp.

4. After the backup is complete, start the directory server on the master server.The master will accumulate changes for the replica.

5. Create the directory for the new replica using the following commands on thehost of the new replica:su - ldapdb2db2 restore database ldapdb2 from /a/big/filesystem/backup replace existing

Use the same file system name used for the backup.6. Start the new replica. The master server will begin sending any changes made

while the directory was being restored.The special tables and directory entries used by master servers areautomatically removed from the directory on the new replica as it is started.

Listing replicasUse the ldapsearch command to list the replicas. For example:ldapsearch —h mymaster —D cn=admin —w admin2pass —b cn=localhost "objectClass=replicaobject"

Note: Bind as the administrator to see the credentials used by the master.

Adding replicasSee “General configuration” on page 28.

Removing replicasUse the ldapdelete command to remove a replica from the directory. For example:ldapdelete —h mymaster -v —D cn=admin —w admin2pass "cn=myreplica, cn=localhost"

Editing replicasUse the ldapmodify command to edit the replica object in the master’s directory.For example, to change the password that the master uses with the replica servers,issue the following command:ldapmodify -h anymaster -v -D cn=admin -w admin2pass -f mymod.ldif

where the mymod.ldif file contains the following information:dn: cn=myreplica,cn=localhostreplicaCredentials: new2pass

Using peer-to-peer replicationPeer replication is a replication in which all servers are masters. However, unlike amulti-master environment, no conflict resolution is done among peer servers.LDAP servers accept the updates provided by peer servers, and update their owncopies of the data. No consideration is given for the order the updates arereceived, or whether multiple updates conflict.

Use peer replication only in environments where the update vectors are wellknown. Updates to particular objects within the directory must be done only byone peer server. This prevents the scenario of one server deleting an object,


followed by another server modifying the object. This scenario creates thepossibility of a Peer server receiving a delete command followed by a modifycommand; which creates a conflict.

ConfiguringAt startup, a server queries the database to determine if there are any replicaobjects. These objects define replica or peer servers for this particular server. Theschema definition for these objects describes how a server can locate and connectto the replica or peer server, as well as other replication properties.

Within the slapd32.conf file there are currently several parameters relating toreplication. If an ibm-slapdMasterServerDn and ibm-slapdMasterServerPW arespecified, this server is presumed to be a read-only replica. Theibm-slapdMasterServerDn and ibm-slapdMasterServerPW in the slapd32.conf filemust match the replicaBindDn and replicaCredentials in the replica objectdefinition found on the master server.

A peer server is designated in the slapd32.conf file with the attributesibm-slapdPeerDn and ibm-slapdPeerPW in the cn=Master,cn=Configuration object.This designates a writable copy of the database. Add a replica definition to allservers within the peer network representing all other peer servers. This isdifferent from the replica, which does not have any replica definitions within thedatabase. The ibm-slapdPeerDn and the ibm-slapdPeerPW in the slapd32.conf filemust match the replicaBindDn and replicaCredentials in the replica definitionfound on the peer servers. Because these passwords must match, the same peerreplica object definition can be used on all peer servers.

A server can be either a replica server or a peer server, it can not be both. Thatmeans that the ibm-slapdMasterServerDn parameter in the slapd32.conf file ismutually exclusive with the ibm-slapdPeerDn configuration file attribute. If bothare defined in the slapd32.conf file, the server does not start and the followingmessage is logged in the slapd.errors file:Can not specify both masterServerDn and peerDn

At this time an ibm-slapdPeerDn is defined for the entire server. Both theibm-slapdPeerDn and ibm-slapdPeerPW directives are in each of the databasesection, for example the rdbm and ldcf databases. All backends must have thesame PeerDn.

ExampleMachine 1 listens on port 389 and is a peer server of machine 2. If the entry dn:cn=Master Server, cn=Configuration is already present in the slapd32.conf file,start the server, turn off replication, and stop the server before proceding.Otherwise, add the following section to the slapd32.conf file on machine 1:dn: cn=Master Server, cn=Configurationcn: Master Serveribm-slapdPeerDn: cn=peeribm-slapdPeerPW: <machine2password>objectclass: ibm-slapdReplicationobjectclass: top

A replica object is added to the machine 1 database through the following ldif file:dn: cn=machine2, cn=localhostcn: machine2objectclass: replicaObjectreplicabindDN: cn=peer

Chapter 3. Tasks 31

replicaCredentials: <machine2password>replicaPort: 389replicaHost: machine2.<fully-qualified-hostname>

Machine 2 listens on port 389 and is a peer server of machine 1. If the entry dn:cn=Master Server, cn=Configuration is already present in the slapd32.conf file,start the server, turn off replication, and stop the server before proceding.Otherwise, add the following section to the slapd32.conf file on machine 2:dn: cn=Master Server, cn=Configurationcn: Master Serveribm-slapdPeerDn: cn=peeribm-slapdPeerPW: <machine1password>objectclass: ibm-slapdReplicationobjectclass: top

A replica object is added to the machine 2 database through the following ldif file:dn: cn=machine1, cn=localhostcn: machine1objectclass: replicaObjectreplicabindDN: cn=peerreplicaCredentials: <machine1password>replicaPort: 389replicaHost: machine1.<fully-qualified-hostname>

UpdatesUpdates that are received from peer servers are not propagated to any otherreplica or peer server definitions. When an update is received by a peer server, theupdate is applied to the database. If the update was received by a peer server, theupdate is applied and processing stops. If the update was made by another client,the directory is updated, and the update information is propagated to the otherpeers. Because peer servers do not propagate updates to other replica definitions,do not configure peer servers as master servers in a master-slave style replication.

Access controlThe peer Dn ID is given the same level of permission as the master DN. Guard thepeer DN ID and password carefully.

Peer-to-peer attributesThe Directory Information Tree object cn=Master Server, cn=Configurationsupports two additional optional attributes:v ibm-slapdPeerDNv ibm-slapdPeerPW

Replica synchronizationIf an interruption occurs during replication use the following procedures to verifywhether the replicas are synchronized with the master:

To test if all replicas are synchronized to the master server:1. Log on as ldapdb2 ( the database instance owner) and issue the following

commands:

Note: For Windows systems you must log on as a member of theAdministrators group and issue the DB2 commands from a DB2command window.

2. db2 connect to ldapdb2

3. db2 "select count (id) from ldapdb2.change″


4. db2 terminate

Replication is synchronized for all replicas if the master’s ldapdb2.change table has0 rows. This means that replication is complete at the time the command wasissued.

To test if a given replica is synchronized to the master server:1. Log on as ldapdb2 ( the database instance owner) and issue the following

commands:


2. db2 connect to ldapdb2

3. db2 "select count (id) from ldapdb2.change″

4. db2 "select count (id) from ldapdb2.progress where (prg = '<replicadn>')"

For example <replica dn> might be: ’cn=replica1, cn=localhost’5. db2 terminate

A given replica is synchronized with the master if the number of rows in themaster’s ldapdb2.progress table (where prg = the dn of the replica object of thegiven replica ) is equal to the number of rows in the masters ldapdb2.change table.This means that replication is complete for the given server at the time thecommand was issued.

Resynchronizing replicasIf one or more of the replicas are out of synchronization, use the following steps tosynchronize all of the replicas.1. Stop the master server.2. Wipe out the change and progress tables.

a. db2 delete from ldapdb2.change

b. db2 delete from ldapdb2.progress

3. Back up the master server database.4. Stop the replica servers5. At this point it is safe to restart the master server because all updates will be

accumulated. Start the master server.6. Restore the master’s back-up database on to the replica.7. Restart each replica server after the restore is complete.

Cleaning change tablesIf your replicas are not synchronized with the master you might want to do thefollowing to clean the change table.1. Stop the master server.2. Log on as the DB instance owner (for example, ldapdb2)


3. Issue the command db2 connect to "ldapdb2"

4. Determine the id number of the change that is blocking replication.db2 select id from change fetch first 1 row only

Chapter 3. Tasks 33

5. If this change has been replicated to all the replica servers and the masterserver is still attempting to send it, you can delete the entry.db2 "delete from ldapdb2.change where (id = X)"

where X is the id determined in the previous step. After the entry is deletedfrom the change table and the master server is restarted, the entry is notreplicated.

Working with DB2 databasesUse the following tasks to create and administer your DB2 database:

Creating a databaseSee “Creating the database” on page 7.

Updating settingsThe DB2 database used by the SecureWay Directory has settings that can be tunedto help improve performance or to address errors reported by DB2 indicating aresource that needs to be increased. The DB2 errors contain the name of theparameter to be reset (but does not recommend a value). Before changing any ofthese parameters, it is important to record the default settings in case you need torestore these settings.

To get the current DB2 parameter settings:1. Log on as the instance owner (for example, ldapdb2):

su - ldapdb2

2. Start the instance (unless it is already started):db2start

3. Get the current state for the database (for example, ldapdb2):db2 get db cfg for ldapdb2 |tee ldapdb2.cfg.orig

To reset a DB2 parameter (for example, APPLHEAPSZ):1. Log on as the instance owner (for example, ldapdb2):

su - ldapdb2

2. Start the instance (unless it is already started):db2start

3. Type the command:db2 update db cfg for ldapdb2 using APPLHEAPSZ 256

4. Stop the directory server and all other applications that use this database:kill -9 ′cat /etc/slapd.pid′db2 force application all

5. Restart the SecureWay Directory server to activate the changed settings:slapd

Backing up a databaseTo back up the directory, use the following commands:su - ldapdb2db2 backup database ldapdb2 to </a/big/filesystem/backup>

Note: Specify a file system with enough free space for the backup. Give only thepath name. DB2 names the backup files based on a timestamp.


Restoring a databaseIf you need to replace your existing database with one that has been previouslybacked up, issue the following command:db2 restore database ldapdb2 from </a/big/filesystem/backup> replace existing

Importing database entriesSee “Populating the directory” on page 22.

Optimizing a databaseAfter a significant amount of update activity on a directory, you might need to usethe DB2 maintenance utilities to free up unused disk space and to make thequeries more efficient. Use the reorgchk utility periodically to see if you have DB2tables that need to be reorganized.

Note: You must stop the server before issuing the reorgchk command.kill -9 ′cat /etc/slapd.pid′db2 reorgchk update statistics on table all

The reorgchk command generates output such as the following:Doing RUNSTATS ....

Table statistics:

F1: 100*OVERFLOW/CARD < 5F2: 100*TSIZE / ((FPAGES-1) * (TABLEPAGESIZE-76)) > 70F3: 100*NPAGES/FPAGES > 80

CREATOR NAME CARD OV NP FP TSIZE F1 F2 F3 REORG-------------------------------------------------------------------------------LDAPDB2 ABSTRACT - - - - - - - - ---LDAPDB2 ACLPERM 2 0 1 1 138 0 - 100 ---LDAPDB2 ACLPROP 2 0 1 1 40 0 - 100 ---LDAPDB2 ADDITIONAL 150600 0 5043 5043 20180400 0 99 100 *-*LDAPDB2 ADDRESS1 709 0 15 15 58847 0 100 100 ---

... etc ...

The *-* characters in the REORG column indicate that a table needs to bereorganized. You can do this with the reorg command. For the given example issuethe command:db2 reorg table LDAPDB2.ADDITIONAL

UTF-8 supportIBM SecureWay Directory supports a wide variety of national language charactersthrough the UTF-8 (UCS Transformation Format) character set. As specified for theLDAP Version 3 protocol, all character data that is passed between an LDAP clientand a server is in UTF-8. Consequently, the directory server can be configured tostore any national language characters that can be represented in UTF-8. Thelimitations on what types of characters can be stored and searched for aredetermined by how the database is created. The database character set can bespecified as ″UTF-8″ or it can be allowed to default to the server system’s localcharacter set (based on the locale, language, and code page environment).

If you specify UTF-8, you can store any UTF-8 character data in the directory.LDAP clients running anywhere in the world (in any UTF-8 supported language)

Chapter 3. Tasks 35

can access and search the directory. In many cases, however, the client has limitedability to properly display the results retrieved from the directory in a particularlanguage/character set.

Why choose anything other than UTF-8?A UTF-8 database has a fixed collation sequence. That sequence is the binary orderof the UTF-8 characters. It is not possible to do language-sensitive collation with aUTF-8 database.

If it is important to your LDAP applications or users to get results for a searchusing an ordering filter (for example, ″name >= SMITH″) as they would expect fortheir native language, then UTF-8 might not be the appropriate character set fortheir directory database. In that instance, the LDAP server system and all clientsystems should run using the same character set and locale. For example, an LDAPserver running in a ″Spanish″ locale with a database created using that localereturns results of searches based on character ordering, as Spanish-language clientswould expect. This configuration does limit your directory user community to asingle end-user character set and collation sequence.

Creating a UTF-8 databaseIf you wish to create your own database using the UTF-8 character set andconfigure it as a custom database for your directory, you can do the following:

Open a DB2 Command Line Processor window. Enter the following command atthe db2 => command prompt:CREATE DATABASE <databasename> USING CODESET UTF-8 TERRITORY US

Remember to update the following stanza in the slapd32.conf file with your actualdatabase name.DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configurationibm-slapdDbName: <databasename>ibm-slapdUserID: <username>ibm-slapdDbUserPW: <password>ibm-slapdDbInstance: <username>

Supported IANA character setsThe IBM SecureWay Directory supports the following IANA character set names byplatform:

Table 3.

Character Locale DB2 Code Page

Set Name Linux NT AIX® Solaris UNIX NT

ISO-8859-1 X X X X 819 1252

ISO-8859-2 X X X X 912 1250

ISO-8859-5 X X X X 915 1251

ISO-8859-6 X X X n/a 1089 1256

ISO-8859-7 X X X n/a 813 1253

ISO-8859-8 X X X n/a 916 1255

ISO-8859-9 X X X n/a 920 1254

IBM437 n/a X n/a n/a 437 437

IBM850 n/a X X n/a 850 850

IBM852 n/a X n/a n/a 852 852

IBM857 n/a X n/a n/a 857 857


Table 3. (continued)

IBM862 n/a X n/a n/a 862 862

IBM864 n/a X n/a n/a 864 864

IBM866 n/a X n/a n/a 866 866

IBM869 n/a X n/a n/a 869 869

TIS-620 n/a X X n/a 874 874

EUC-JP X n/a X X 954 n/a

EUC-KR n/a n/a X X 970 n/a

EUC-CN n/a n/a X X 1383 n/a

EUC-TW n/a n/a X X 964 n/a

Shift-JIS X X X X 932 943

KSC n/a X n/a n/a n/a 949

GBK n/a X X n/a 1386 1386

Big5 n/a X X X 950 950

Server utilitiesThe server utilities (bulkload, ldif2db, and db2ldif) have been enhanced torecognize the latest version of LDIF.

Manual creation of an LDIF file containing UTF-8 values is difficult. To simplifythis process, a charset extension to the LDIF format is supported. This extensionallows an IANA character set name to be specified in the header of the LDIF file(along with the version number). A limited set of the IANA character sets aresupported.

Examples: You can use the optional charset tag so that the server utilitiesautomatically convert from the specified character set to UTF-8 as in the followingexample:version: 1charset: ISO-8859-1

dn: cn=Juan Griego, o=University of New Mexico, c=UScn: Juan Griegosn: Griegodescription:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdtitle: Associate Deantitle: [title in Spanish]jpegPhoto:< file:///usr/local/photos/jgriego.jpg

In this instance, all values following an attribute name and a single colon aretranslated from the ISO-8859-1 character set to UTF-8. Values following an attributename and a double colon (such as description:: V2hhdCBhIGNhcm... ) should bebase 64-encoded, and are expected to be either binary or UTF-8 character strings.Values read from a file, such as the jpegPhoto attribute specified by the URL in theexample above, are also expected to be either binary or UTF-8. No translation fromthe specified ″charset″ to UTF-8 is done on those values.

In this example of an LDIF file without the charset tag, content is expected to be inUTF-8:# IBM SecureWay Directory sample LDIF file## The suffix "o=IBM, c=US" should be defined before attempting to load# this data.

Chapter 3. Tasks 37

version: 1

dn: o=IBM, c=USobjectclass: topobjectclass: organizationo: IBM

dn: ou=Austin, o=IBM, c=USou: Austinobjectclass: organizationalUnitseealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US

This same file could be used without the version: 1 header information, as inprevious releases of the IBM SecureWay Directory:# IBM SecureWay Directory sample LDIF file##The suffix "o=IBM, c=US" should be defined before attempting to load#this data.

dn: o=IBM, c=USobjectclass: topobjectclass: organizationo: IBM

dn: ou=Austin, o=IBM, c=USou: Austinobjectclass: organizationalUnitseealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US

Configuring the directory to use a databaseYou must tell the server to use the database that you created. Scroll down to thelast entry in the slapd32.conf file and insert the lines indicated in bold type before’cn: Directory’:dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdRdbmBackend

ibm-slapdDbInstance: ldapdb2ibm-slapdDbName: ldapdb2ibm-slapdDbUserId: ldapdb2ibm-slapdDbUserPW: <password>

cn: Directory

where ldapdb2 is the name of your database and <password> is the password youset in step 4 of “Creating the database” on page 7.

Working with a change logThe change log records changes (such as schema and entry changes) in the typicalLDAP entry structure that can be retrieved through the ldapapi. The change logenables a SecureWay Directory client application to retrieve a set of changes thathave been made to a SecureWay Directory server database. The client (which mightbe another SecureWay Directory server) might then update its own replicated orcached copy of the data.

Change log configurationBecause the IBM SecureWay Directory schema can be changed, it is possible tohave any modifications to the schema logged to the change log. Each configurationcombination requires different entries in the slapd32.conf file.


Before you configure the change log you must identify the suffix that it uses. In thefollowing examples, the suffix for the change log is ″cn=changelog″. Note that thissuffix can be changed.

After creating the change log database, you must ensure that it has the correctaccess rights set and configured correctly.

The following instructions assume that the default LDAP install and configurationparameters were used to configure the directory database, and that the change logdatabase name is ″ldapcl″.

For AIX, use the db2 command shell to perform the following commands. Thesecommands assume that the user is logged in as ’root’.1. Change user to the ldapdb2 user

su - ldapdb2

2. Create the changelog databasedb2 create database ldapcl on /home/ldapdb2/using codeset UTF-8 territory US

3. Update the DBHEAP configuration parameter for the databasedb2 update database configuration for ldapcl using DBHEAP 500

4. Return to the ’root″ user by pressing Ctrl d

Logging schema changesThe IBM SecureWay Directory slapd32.conf file contains a stanza that definesschema configuration. For example:dn: cn=SchemaDB,cn=LDCF Backends,cn=IBMSecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdLdcfBackendcn: SchemaDBibm-slapdSuffix: cn=schema

To enable schema updates to be shadowed to the change log, the preceding stanzais changed to:dn: cn=SchemaDB,cn=LDCF Backends,cn=IBMSecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdLdcfBackendcn: SchemaDBibm-slapdPlugin: database /bin/libcl.dll CLInit cn=changelogibm-slapdSuffix: cn=schema

Note the additional line. The last parameter in this line, ″cn=changelog″ tells theIBM SecureWay Directory server which change log database it must log schemachanges to. Configuration of this change log database is discussed in the nextsection. For AIX, replace .dll to .a in the library names.

Multiple database configurationThe IBM SecureWay Directory can log changes to a separate database. There aretwo distinct databases, one that holds the actual data and another to hold anychanges. In the following example the name of that file isd:/slapd/etc/slapd32.cl.conf, and the name of the second database is cldb2:dn: cn=Change Log,cn=RDBM Backends,cn=IBMSecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdRdbmBackend

Chapter 3. Tasks 39

cn: Directoryibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_initibm-slapdSuffix: cn=changelogibm-slapdDbName: cldb2ibm-slapdDbUserPW: xxxibm-slapdDbUserID: db2user

Notes:

1. This slapd32.cl.conf sample file is shipped in the same directory asslapd32.conf.

2. As with the Directory entry, ensure that the ibm-slapdDbUserPW is all one line(make sure carriagereturn/line feeds are not inserted in the password).

Change log access controlThe change log can be accessed through normal mechanisms as the primary tree.However, the directory entry the client binds as does not exist in the change logdirectory tree. This is more a statement of policy, because the entry can exist in thechange log database. Administration of the changelog database is easier, however,if no bind entries are contained in it.

After entries that are allowed to access the change log are identified, the ACLs forthe root level of the change log tree need to be changed (to enable users to havefull read, search and compare privileges for the tree or subtree). Do not configureanonymous access for your change log tree, do not grant write or delete access tothe tree. This needs to be done separately for each change log database in thesystem.

Note: Access to the change log gives access to all changed entries in the shadoweddirectory, even if permissions are restricted on the shadowed directory.

Change log expiration of entriesYou can limit the number of entries the change log can hold by using the″changelogmaxentries <integer> value″, which is the maximum number of entriesin the change log that can be set. The values can be 0 to the maximum integer.This value is defined in the Changelog entry where the change log database isdefined: .dn: cn=Change Log,cn=RDBM Backends,cn=IBMSecureWay,cn=Schemas,cn=Configurationobjectclass: topobjectclass: ibm-slapdRdbmBackendcn: Directoryibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_initibm-slapdSuffix: cn=changelogibm-slapdDbName: cldb2ibm-slapdDbUserPW: xxxibm-slapdDbUserID: db2useribm-slapdChangeLogMaxEntries 5000

In this instance the maximum number of entries the change log can hold is 5000.The default is to have no limitation.

Change log schemaIn this release of the IBM SecureWay Directory an object class (″changeLogEntry″)is used to represent changes applied to an SecureWay Directory server. It alsosuggests a common location for a container that can hold these objects. The clientmight update its local copy of directory information by reading the entries withinthe container and then applying any changes to its local database.


The location of the container that holds ″changeLogEntry″ objects is obtained byreading the ″changeLog″ attribute of the root DSE of a server. For example, if theroot of the container is ″cn=changelog″, then the root DSE must have an attributenamed ″changeLog″ with the value ″cn=changelog″.

The changeLogEntry object classThe ″changeLogEntry″ object class is used to represent changes made to a directoryserver. The set of changes is given by the ordered set of all entries within thechange log container as defined by ″changeNumber″. The change log informationcan have entries added and deleted.

changeLogEntry attributeschangeNumber

The change number as assigned by the supplier. This integer must increaseas new entries are added, and always be unique within a given server.Syntax: INTEGER

targetdnThe distinguished name of the entry which was added, modified, ordeleted. In the case of a ″modrdn″ operation, the targetdn gives the DN ofthe entry before it was modified. Syntax: DN

changeTypeThe type of change (″add″, ″delete″, ″modify″, or ″modrdn″). Syntax:DirectoryString

changesThe changes that were made to the directory server. These changes are inLDIF format. See “Ldif utility” on page 55 for additional information aboutthe ldif command utility.

newRDNThe new RDN (Relative Distinguished Name) of the entry, if thechangeType is ″modrdn″. If the changeType attribute does not have the″modrdn″ value then there are no values contained in the newRDNattribute. Syntax: DN

deleteOldRDNA flag which tells whether the old RDN of the entry should either beretained as a distinguished attribute of the entry or deleted. Syntax:BOOLEAN

newSuperiorIf present, it gives the name of the entry (which becomes the immediatesuperior of the existing entry). Syntax: DN

changeTimeThe time when the change was made. Syntax: Generalized Time

modifiersNameThe DN making the change. Syntax: DirectoryString

changelogmaxentriesIdentifies the maximum number of entries in the change log file. Syntax:INT

Note: Bind DNs are restricted to the Admin DN and to a DN explicitly determinedby the SecureWay Directory administrator during configuration.

Chapter 3. Tasks 41

Examples using the ldapsearch commandExample 1: This example using the ldapsearch command retrieves all change logentries that are recording add operations:ldapsearch -b "cn=changelog" "(changetype=add)"

changenumber=10,cn=changelogobjectclass=topobjectclass=changelogentrychangenumber=10targetdn=cn=David Campbell, ou=Widget Division, ou=Austin, o=IBM_US, c=USchangetime=19990412160345changetype=addchanges=objectclass: organizationalPersontelephonenumber: 1-812-855-7509internationalisdnnumber: 755-7509title: Mfg. Assemblyseealso: cn=Mary Burnnet, ou=Widget Division, ou=Austin, o=IBM_US, c=USpostalcode: 1514cn: David Campbell

Example 2: This search example retrieves all delete changes where thechangenumber attribute is greater than or equal to 5:ldapsearch -b "cn=changelog" "(& (changetype=delete)(changenumber>=5))"

changenumber=9,cn=changelogobjectclass=topobjectclass=changelogentrychangenumber=9targetdn=cn=david campbell,ou=widget division,ou=austin,o=ibm_us,c=uschangetime=19990412160331changetype=delete

Example 3: This search example retrieves all modify operations, where thechangetime attribute is greater than 199904141915000:ldapsearch -b "cn=changelog" "(&(changetype=modify)(changetime>=199904141915000))"

changenumber=32,cn=changelogobjectclass=topobjectclass=changelogentrychangenumber=32targetdn=cn=bowling team,ou=groups,o=ibm_us,c=uschangetime=19990414191505changetype=modifychanges=NOT ASCII




Examples of the changeLogEntry Object ClassExample 1: A changeLogEntry representing the addition of a new entry to thedirectory:dn: changenumber=1923, cn=changelogchangenumber: 1923targetdn: cn=Barbara Johnson, ou=Accounting, o=Ace Industry, c=USchangetype: addchanges: cn: Barbara Johnson\ncn: Babs Johnson\nsn: Johnson\n

givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: [email protected]\nobjectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\nobjectclass: inetOrgPerson

Example 2: A changeLogEntry representing the deletion of an entry from thedirectory:dn: changenumber=2933, cn=changelogchangenumber: 2933targetdn: cn=Gern Johnson, ou=Product Testing, o=Ace Industry, c=USchangetype: delete

Example 3: A changeLogEntry representing the modification of an entry in thedirectory:dn: changenumber=5883, cn=changelogchangenumber: 5883targetdn: cn=Bjorn Johnson, ou=Product Development, o=Ace Industry, c=USchangetype: modifychanges: delete: telephonenumber\ntelephonenumber: 1212\n-\n

add: telephonenumber\ntelephonenumber: +1 212 555 1212\n-

Example 4: A changeLogEntry representing a modrdn operation performed on anentry in the directory:dn: changenumber=10042, cn=changelogchangenumber: 10042

targetdn: cn=Bjorn Johnson, ou=Product Development, o=Ace Industry, c=USchangetype: modrdnnewrdn: cn=Bjorn J Johnsondeleteoldrdn: FALSE

Working with Administration UtilitiesUsing the change log facility affects the administration utilities in the followingway:v The bulkload utility cannot be used to load the change log from a ldif file. To

load the change log from a ldif file, use the ldif2db command and an ldif filecontaining change log entries created by the db2ldif command. See thefollowing item.

v To dump the change log database to an ldif file using the db2ldif command, the-s option must be used. The argument to this option is the change log suffix(″cn=changelog″) defined from your configuration file. If this option is not used,then db2ldif dumps the first rdbm database defined in the slapd32.conf file. Forexample:To dump the contents of the change log to a file named ldif.cl:db2ldif -o ldif.cl -s "cn=changelog"

To pre-load the change log with the contents of an ldif file named ldif.cl:ldif2db -i ldif.cl

Chapter 3. Tasks 43

Note: Do not modify the changelog database backend directly using ldapadd,ldapdelete, ldapmodify, or ldapmodrdn on the change suffix″cn=changelog″.

Unconfiguring changelogTo unconfigure the changelog you can either remove orcomment out the changelogstanzas.#dn: cn=Change Log,cn=RDBM Backends,cn=IBM#SecureWay,cn=Schemas,cn=Configuration#objectclass: top#objectclass: ibm-slapdRdbmBackend#cn: Directory#ibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_init#ibm-slapdSuffix: cn=changelog#ibm-slapdDbName: cldb2#ibm-slapdDbUserPW: xxx#ibm-slapdDbUserID: db2user

Working with referralsReferrals provide a way for servers to refer clients to additional directory servers.With referrals you can:v Distribute namespace information among multiple serversv Provide knowledge of where data resides within a set of interrelated serversv Route client requests to the appropriate server

Some of the advantages of using referrals are the ability to:v Distribute processing overhead, providing primitive load balancingv Distribute administration of data along organizational boundariesv Provide potential for widespread interconnection, beyond an organization’s own

boundaries

This section describes how to use the referral object class and the ref attribute toconstruct entries in an LDAP directory containing references to other LDAPdirectories. This section also describes how to associate multiple servers usingreferrals and an example of this.

Using the referral object class and the ref attributeThe referral object class and the ref attribute are used to facilitate distributed nameresolution or to search across multiple servers. The ref attribute appears in an entrynamed in the referencing server. The value of the ref attribute points to an entrymaintained in the referenced server.

Creating entriesFollowing is an example configuration that illustrates the use of the ref attribute.


In the example, Server A holds references to two entries: o=ABC, c=US ando=XYZ, c=US. For the o=ABC, c=US entry, Server A holds a reference to Server Band for the o=XYZ, c=US entry, Server A holds a reference to Server C.

The recommended setup of referrals is to structure the servers into a hierarchybased on the subtrees they manage. Then, provide ″forward″ referrals from serversthat hold higher (closer to the root of the hierarchy) information and set thedefault referral to point back to its parent server.

Associating servers with referralsTo associate servers through referrals:v Use referral objects to point to other servers for subordinate references.v Define the default referral to point somewhere else, typically to the parent

server.

Note: Referral objects can be seen from command line LDAP utilities by specifyingthe -M option.

Pointing to other serversUse referral objects to point to the other servers for subordinate references, that is,portions of the namespace below this server that it does not service directly.

Referral objects, like other objects, go in the backend (DB2). Referral objects consistof:

dn: Specifies the distinguished name. It is the portion of the namespace servedby the referenced server.

objectclass:Specifies the value of the objectclass ″referral″.

ref: Specifies the LDAP Web address of the server. This Web address consists ofthe ldap:// identifier, the hostname:port, and a DN. The identifier can beeither a host name string or a TCP/IP address. The DN requires a slash (/)before it to delimit it from the hostname:port, and should match the DN ofthe referral object. It is highly recommended that the DN specified in thevalue of the referral attribute match the DN of the referral object. Typically,it is an entry in a naming context at or below the naming context held bythe referencing server.

Server A

Server B Server C

dn: o=ABC, c=USref: ldap://hostB/o=ABC, c=USobjectclass: referral

dn: o=XYZ, c=USref: ldap://hostC/o=XYZ, c=USobjectclass: referral

dn: o=ABC, c=USo: ABCother attributes

dn: o=ABC, c=USo: XYZother attributes

Figure 1. Example of using the ref attribute

Chapter 3. Tasks 45

dn: o=IBM,c=USobjectclass: referralref: ldap://9.130.25.51:389/o=IBM,c=US

Defining the default referralDefine a default referral in the slapd32.conf file to reference a directory on anotherserver. The default referral can be used to point to:v The immediate parent of this server (in a hierarchy)v A ″more knowledgeable″ server, such as the uppermost server in the hierarchyv A ″more knowledgeable″ server that possibly serves a disjoint portion of the

namespace

Note: The default referral LDAP URL does not include the DN portion. It includesonly the ldap:// identifier and the hostname:port.

For example:# referraldn: cn=Referral, cn=Configurationobjectclass: topobjectclass: ibm-slapdReferralcn: Referralibm-slapdReferral ldap://dcecds3.endicott.ibm.com:389ibm-slapdReferral ldap://<additional hostname:port>ibm-slapdReferral ldap://<additional hostname:port>ibm-slapdReferral ldap://<additional hostname:port>

Deleting default referrals: To remove a default referral, you need to remove orcomment out the appropriate line that contains the ldap identifier and thehostname:port information in the slapd32.conf file. For example:# referraldn: cn=Referral, cn=Configurationobjectclass: topobjectclass: ibm-slapdReferralcn: Referralibm-slapdReferral ldap://dcecds3.endicott.ibm.com:389#ibm-slapdReferral ldap://<additional hostname:port>ibm-slapdReferral ldap://<additional hostname:port>ibm-slapdReferral ldap://<additional hostname:port>

Binding with a distributed namespaceWhen performing searches, the same DN that was used to bind to the originalserver is used to bind to the referred-to server, unless the SecureWay Directoryapplication is designed to modify the bind DN and credentials. The correct accessmust be set up for the same DN to be able to bind to both servers for chasing thereferrals.

An example of distributing the namespace through referralsFollowing are the steps involved in distributing the namespace using referrals.1. Plan your namespace hierarchy.

country - UScompany - IBM, LotusorganizationalUnit - IBM Austin, IBM Endicott, IBM Raleigh, IBM HQ

2. Set up multiple servers, each containing portions of the namespace.


Server descriptions:

Server AA server used to locate other servers in the U.S. With no otherknowledge, clients can come here first to locate information for anyonein the U.S.

Server BA hub for all data pertaining to IBM in the U.S. Holds all HQinformation directly. Holds all knowledge (referrals) of where otherIBM data resides.

Server CHolds all IBM Austin information.

Server DHolds all IBM Endicott information.

Server EHolds all Lotus® information.

3. Set up referral objects to point to the descendants in other servers.

Servers can also define a default referral, which is used to point to a ″moreknowledgeable″ server for anything that is not underneath them in thenamespace.

Note: The default referral LDAP Web address does not include the DN portion.

Following is an arrangement of the same five servers, showing the referral objectsin the database as well as the default referrals that are used for superior references.

Server Eo=Lotus, c=US

ou=HQ, o=IBM, c=US

Server Dou=Endicott, o=IBM, c=US

Server Cou=Austin, o=IBM, c=US

o=IBM, c=US

Server Ac=US

Server B

Figure 2. Setting up the servers

Pointer to Server B

Pointer to Server E

dn: o=IBM, c=USobjectClass: referralref: ldap://ibm.com:389/o=IBM, c=US

dn: o=Lotus, c=USobjectClass: referralref: ldap://lotus.com:389/o=Lotus, c=US

Figure 3. Server A database (ldif input)

Chapter 3. Tasks 47

Viewing error logsTo view the error log issue the following command:more /tmp/slapd.errors

where tmp/slapd.errors is your error log.

Note: tmp/slapd.errors is the default error log.

Server A: Services

Server C: Services

Server D: Services

Server E: Services

“ ”c=US

“ ”ou=Austin,o=IBM,c=US

“ ”ou=Endicott,o=IBM,c=US

“ ”ou=Lotus,c=US

Database

Configuration

Configuration

Configuration

Database

Database

Database

Database

dn: o=IBM,c=USobjectClass: referralref: ldap://ibm.com:389/o=IBM,c=US

dn: o=Lotus,c=USobjectClass: referralref: ldap://lotus.com:389/o=Lotus,c=US

referral ldap://ibm.com:389

referral ldap://ibm.com:389

referral ldap://US.white.pages.com:1234

dn: ou=LDAP development,ou=Austin,o=IBM,c=USobjectClass: organization

dn: ou=Directory Team,ou=Endicott,o=IBM,c=USobjectClass: organization

dn: ou=Firewall Team,ou=Endicott,o=IBM,c=USobjectClass: organization

dn: cn=Mikey,ou=Lotus,c=USobjectClass: person

dn: ou=Austin,o=IBM,c=USobjectClass: referralref: ldap://austin.ibm.com:389/ou=Austin,o=IBM,c=US

dn: ou=Endicott, o=IBM, c=USobjectClass: referralref: ldap://endicott.ibm.com:789/ou=Endicott,o=IBM,c=US

dn: ou=HQ,o=IBM,c=USobjectClass: organizationalUnitdescription: Headquarters...

Server B: Services “ ”o=IBM,c=US

Configuration

referral ldap://US.white.pages.com:1234

Entry Data

Entries

Figure 4. Referral example summary


Understanding distinguished names (DNs)Every entry in the directory has a distinguished name (DN). The DN is the namethat uniquely identifies an entry in the directory. A DN is made up ofattribute:value pairs, separated by commas, for example:cn=Ben Gray,ou=editing,o=New York Times,c=UScn=Lucille White,ou=editing,o=New York Times,c=UScn=Tom Brown,ou=reporting,o=New York Times,c=US

Any of the attributes defined in the directory schema may be used to make up aDN. The order of the component attribute value pairs is important. The DNcontains one component for each level of the directory hierarchy from the rootdown to the level where the entry resides. LDAP DNs begin with the most specificattribute (usually some sort of name), and continue with progressively broaderattributes, often ending with a country attribute. The first component of the DN isreferred to as the Relative Distinguished Name (RDN). It identifies an entrydistinctly from any other entries that have the same parent. In the examples above,the RDN ″cn=Ben Gray″ separates the first entry from the second entry, (with RDN″cn=Lucille White″). These two example DNs are otherwise equivalent. Theattribute:value pair making up the RDN for an entry must also be present in theentry. (This is not true of the other components of the DN.)

Follow this example to create a distinguished name in the slapd32.conf file:DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configurationibm-slapdDbName: <databasename>ibm-slapdUserID: <username> (Same as login. See Installation Step 4.)ibm-slapdDbUserPW: <password>ibm-slapdDbInstance: <username> (See Installation Step 3.)

See “Appendix B. IBM SecureWay Directory Configuration Schema” on page 117for more information on schemas and attributes.

Distinguished Name SyntaxThe Distinguished Name (DN) syntax supported by this server is based on RFC2253. The Backus Naur Form (BNF) syntax is defined as follows:<name> ::= <name-component> ( <spaced-separator> )

| <name-component> <spaced-separator> <name>

<spaced-separator> ::= <optional-space><separator><optional-space>

<separator> ::= "," | ";"

<optional-space> ::= ( <CR> ) *( " " )

<name-component> ::= <attribute>| <attribute> <optional-space> "+"

<optional-space> <name-component>

<attribute> ::= <string>| <key> <optional-space> "=" <optional-space> <string>

<key> ::= 1*( <keychar> ) | "OID." <oid> | "oid." <oid><keychar> ::= letters, numbers, and space

<oid> ::= <digitstring> | <digitstring> "." <oid><digitstring> ::= 1*<digit><digit> ::= digits 0-9

Chapter 3. Tasks 49

<string> ::= *( <stringchar> | <pair> )| '"' *( <stringchar> | <special> | <pair> ) '"'| "#" <hex>

<special> ::= "," | "=" | <CR> | "+" | "<" | ">"| "#" | ";"

<pair> ::= "\" ( <special> | "\" | '"')<stringchar> ::= any character except <special> or "\" or '"'

<hex> ::= 2*<hexchar><hexchar> ::= 0-9, a-f, A-F

A semicolon (;) character can be used to separate RDNs in a distinguished name,although the comma (,) character is the typical notation.

White-space characters (spaces) might be present on either side of the comma orsemicolon. The white-space characters are ignored, and the semicolon is replacedwith a comma.

In addition, space (’ ’ ASCII 32) characters may be present either before or after a’+’ or ’=’. These space characters are ignored when parsing.

A value may be surrounded by double quotation (’″’ ACSII 34) characters, whichare not part of the value. Inside the quoted value, the following characters canoccur without any escaping:v A space or ″#″ character occurring at the beginning of the stringv A space character occurring at the end of the stringv One of the characters ″’″, ″=″, ″+″, ″\″, ″<″, ″>″, or ″;″

Alternatively, a single character to be escaped may be prefixed by a backslash (’\’ASCII 92). This method can be used to escape any of the characters listedpreviously and the double quotation marks (’″’ ASCII 34) character.

This notation is designed to be convenient for common forms of names. Followingare further examples of distinguished names written using this notation. First is aname containing three components. The first of the components is a multivaluedRDN. A multivalued RDN contains more than one attribute:value pair and can beused to distinctly identify a specific entry in cases where a simple CN value mightbe ambiguous:OU=Sales+CN=J. Smith,O=Widget Inc.,C=US

This example shows a method of escaping a comma in an organization name:CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB

Pseudo DNsPseudo DNs are used in access control definition and evaluation. The LDAP/DB2directory contains several pseudo DNs (for example, ″group:cn=this″ and″access-id:cn=Anybody″), which are used to refer to large numbers of DNs thatshare a common characteristic, in relation to either the operation being performedor the object on which the operation is being performed.

Three pseudo DNs are supported by LDAP version 3:v access-id: cn=this


When specified as part of an ACL, this DN refers to the bindDn, which matchesthe dn on which the operation is performed. For example, if an operation isperformed on the object ″cn=personA, ou=IBM, c=US″ and the bindDn is″cn=personA, ou=IBM, c=US″, the permissions granted are a combination ofthose given to ″cn=this″ and those given to ″cn=personA, ou=IBM, c=US″.

v group: cn=anybodyWhen specified as part of an ACL, this DN refers to all users, even those thatare unauthenticated. Users cannot be removed from this group, and this groupcannot be removed from the database.

v group: cn=AuthenticatedThis DN refers to any dn that has been authenticated by the directory. Themethod of authentication is not considered.

Note: ″cn=Authenticated″ refers to a DN that has been authenticated anywhereon the server, regardless of where the object representing the DN islocated. It should be used with caution, however. For example, under onesuffix, ″cn=Secret″ could be a node called ″cn=Confidential Material″which has an aclentry of ″group:cn=Authenticated:normal:rsc″. Underanother suffix, ″cn=Common″ could be the node ″cn=Public Material″. Ifthese two trees reside on the same server, a bind to ″cn=Public Material″would be considered authenticated, and would get permission to thenormal class on the ″cn= Confidential Material″ object.

Some examples of pseudo DNs:

Example 1Consider the following ACL for object: cn=personA, c=USAclEntry:access-id: cn = this:critical:rwscAclEntry: group: cn=Anybody: normal:rscAclEntry: group: cn=Authenticated: sensitive:rcs

Table 4.

User Binding as Would receive

cn=personA, c=US normal:rsc:sensitive:rcs:critical:rwsc

cn=personB, c=US normal:rsc:sensitive:rsc

NULL (unauth.) normal:rsc

In this example, personA receives permissions granted to the ″cn=this″ ID,and permissions given to both the ″cn=Anybody″ and ″cn=Authenticated″pseudo DN groups.

Example 2Consider the following ACL for object: cn=personA, c=USAclEntry: access-id:cn=personA, c=US: object:adAclEntry: access-id: cn = this:critical:rwscAclEntry: group: cn=Anybody: normal:rscAclEntry: group: cn=Authenticated: sensitive:rcs

For an operation performed on cn=personA, c=US:

Table 5.

User Binding as Would receive

cn=personA, c=US object:ad:critical:rwsc

cn=personB, c=US normal:rsc:sensitive:rsc

NULL (unauth.) normal:rsc

Chapter 3. Tasks 51

In this example, personA receives permissions granted to the ″cn=this″ ID,and those given to the DN itself ″cn=personA, c=US″. Note that the grouppermissions are not given because there is a more specific aclentry(″access-id:cn=personA, c=US″) for the bind DN (″cn=personA, c=US″).


Chapter 4. Command line utilities

This section provides a brief overview of the utilities that can be run from acommand prompt.

Client Utilities

v “Ldapdelete utility”v “Ldapmodify utility” on page 54v “Ldapadd utility” on page 54v “Ldapmodrdn utility” on page 54v “Ldapsearch utility” on page 54

Server Utilities

v “Ldif utility” on page 55v “Ldif2db utility” on page 56v “Db2ldif utility” on page 59v “Bulkload utility” on page 56

The ldapdelete, ldapmodify, ldapadd, ldapmodrdn, and ldapsearch utilities alluse the ldap_bind API. When bind is invoked, several results can be returned.Following are bind results using various combinations of user IDs and passwords.v If specifying the admin DN, the password must be correctly specified or the

bind is not successful.v If a null DN is specified, or a 0 length DN is specified, you receive

unauthenticated access.v If a DN is specified, and is non-null, a password must also be specified or an

error is returned.v If a DN and password are specified but do not fall under any suffix in the

directory, a referral is returned if a default referral is defined. Otherwise, themessage No such object is returned.

v If a DN and password are specified and are correct, the user is bound with thatidentity.

v If a DN and password are specified but the DN does not exist, unauthenticatedaccess is given.

v If a DN and password are specified and the DN exists but the object does nothave user password, an error message is returned.

Client utilitiesThis section provides a brief description of the client utilities. For more detailedinformation see ″Chapter 2. Ldap Utilities″ in the SecureWay Directory Version 3.2:Client SDK Programming Reference.

Ldapdelete utilityThe LDAP delete-entry tool ldapdelete is a shell-accessible interface to theldap_delete library call.

ldapdelete opens a connection to an LDAP server and binds and deletes one ormore entries. If one or more Distinguished Name (DN) arguments are provided,


entries with those DNs are deleted. Each DN should be a string-represented DN. Ifno DN arguments are provided, a list of DNs is read from standard input (or froma file if the -f flag is used).

Ldapmodify utilityThe LDAP modify-entry and LDAP add-entry tool ldapmodify is a shell-accessibleinterface to the ldap_modify and ldap_add library calls. ldapadd is implementedas a renamed version of ldapmodify. When invoked as ldapadd the -a (add newentry) flag is turned on automatically.

ldapmodify opens a connection to an LDAP server, binds, and modifies or addsentries. The entry information is read from standard input or from a file, throughthe use of the -f option.

Ldapadd utilityThe LDAP modify-entry and LDAP add-entry tool ldapmodify is a shell-accessibleinterface to the ldap_modify and ldap_add library calls. ldapadd is implementedas a renamed version of ldapmodify. When invoked as ldapadd the -a (add newentry) flag is turned on automatically.

ldapadd opens a connection to an LDAP server, binds, and adds entries. The entryinformation is read from standard input or from a file through the use of the -foption. The entry information must be in LDIF format.

Ldapmodrdn utilityLDAP modify-entry RDN tool ldapmodrdn is a shell-accessible interface to theldap_modrdn library call.

ldapmodrdn opens a connection to an LDAP server and binds and modifies theRDN of entries. The entry information is read from standard input, from a file,through the use of the - f option, or from the command-line pair DN and RDN.

See ldap_dn in the Programming Reference for information about RDNs (RelativeDistinguished Names) and DNs (Distinguished Names).

Ldapsearch utilityThe LDAP search tool ldapsearch is a shell-accessible interface to the ldap_searchlibrary call.

ldapsearch opens a connection to an LDAP server and binds and performs asearch using the filter. The filter should conform to the string representation forLDAP filters (see ldap_search for more information on filters).

If ldapsearch finds one or more entries, the attributes specified by attrs areretrieved and the entries and values are printed to standard output. If no attrs arelisted, all attributes are returned.

Server utilitiesThis sections describes the server utilities.


Ldif utilityThe LDAP Data Interchange Format (LDIF) tool ldif is a shell-accessible utility thatconverts arbitrary data values to LDIF. It reads input values from standard inputand produces LDIF.

Synopsis:ldif [-b] <attrname>

Command Line Option:All options are case sensitive.

-b Input is a single raw binary value

<attrname>The name of the attribute for which values are to be converted.Without the -b option, ldif considers each line of standard input tobe a separate value of the attribute.

LDIF is used to represent LDAP entries in text form. The purpose of thisinformation is to describe LDIF, as used by the ldapmodify, ldapadd, andldapsearch command-line utilities.

Format exampleThe basic form of an LDIF entry is:dn: <distinguished name>:<attrtype>: <attrvalue><attrtype>: <attrvalue>...

A line can be continued by starting the next line with a single space or tabcharacter, for example:dn: cn=Barbara J Jensen, o=University of Michi

gan, c=US

Multiple attribute values are specified on separate lines, for example:cn: Barbara J Jensencn: Babs Jensen

If an <attrvalue> contains a non-printing character, or begins with a space or acolon ″:″, the <attrtype> is followed by a double colon and the value is encoded inbase 64 notation. The value that begins with a space would be encoded like this:cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=

Multiple entries within the same LDIF file are separated by blank lines.

Adding the first replica object would look something like the following in LDIFformat:dn: cn=myReplica, cn=localhostcn: myReplicaobjectclass : replicaObjectreplicaHost: mymachine.austin.ibm.comreplicaBindDn: cn=Admin, c=USreplicaCredentials: passwordreplicaPort: 1010

The replicaBindDn (cn=Admin, c=US) must be the same as the master server DNon the replica (mymachine.austin.ibm.com). Similarly, replicaCredentials must bethe same as the masterServerPassword on the replica, and the replicaPort must bethe same as the port on the replica.

Chapter 4. Command line utilities 55

LDIF ACL exampledn: cn=John Doe, ou=Austin, o=IBM, c=USobjectclass: topobjectclass: personobjectclass: organizationalPersoncn: John Doesn: Doedept: abcdaclEntry: access-id:cn=Bert Hello, ou=Austin, o=IBM, c=US:object:da:normal:rwsc:sensitive:rscaclEntry: group:cn=Anybody::normal:rscaclEntry: access-id:cn=Amy Too, ou=Austin, o=IBM, c=US:object:da:normal:rwsc:sensitive:rsc:critical:raclPropagate:TRUEentryOwner: group:cn=personnel, ou=Austin, o=IBM, c=USownerPropagate: TRUE

Ldif2db utilityThis program is used to load entries specified in text (LDIF) into a directory storedin a relational database. The database must already exist. ldif2db can be used toadd entries to an empty directory database or to a database that already containsentries.

Synopsis:ldif2db -i <inputfile>

Command Line Options:All options are case insensitive.

-i <inputfile>Specify the name of the LDIF input file, containing directoryentries in LDIF format. This option is required. If the file is not inthe current directory, a full path and file name must be specified.

All other command line inputs result in a syntax error message, after which thecorrect syntax is displayed.

Note: When records are added using ldif2db, the master server should be stoppedand then restarted immediately. If replicas are added before the server isrecycled, incorrect replication will result.

Bulkload utilityThe bulkload utility is used to load the directory data from an ldif file. It is afaster alternative to ldif2db and is available for bulk-loading large amounts of datain LDIF format.

Synopsis:bulkload -i <ldiffile>

Command Line Options:

-i <ldiffile>Specifies the name of the input file containing the LDIF data to beloaded into the directory. It might include a path. The file/usr/ldap/examples/sample.ldif contains some sample data in thecorrect format.

Note: Bulkload might fail to load ldif files that contain certain UTF-8 characters.This is because of a problem with the DB2 LOAD tool when parsing thedefault bulkload string delimiter | in multi-byte character sets. Reassign thestring delimiter to $ by:set STRING_DELIMITER=$


For better performance the bulkload tool assumes that the data in the input file iscorrect or that the data has been checked in an earlier loading. The bulkload toolcan, however, perform some basic checks on the input data.

If you are unsure of the correctness of your data, you can enable the checkingprocess. To enable the checking, set these two environment variables:set ACLCHECK=YESset SCHEMACHECK=YES

The defaults are:ACLCHECK=YESSCHEMACHECK=NO

The SCHEMACHECK environment variable verifies that individual directoryentries are valid based on the object class definitions and attribute type definitionsfound in the configuration files.

The schema check verifies that all object classes and attributes have been defined,that all attributes specified for each entry comply with the list of ″required″ and″allowed″ attributes in the object class definition, and that binary attribute valuesare in the correct 64-bit encoded form. The possible settings for SCHEMACHECKare:

YES Schema checking is done on the data, before adding it to the directory.

NO No schema checking is done on the data before adding it to the directory.This provides much faster performance. This option assumes that the datain the input file is valid. This is the default option.

ONLY Schema checking is done on the data, but it is not added to the directory.This option provides the most feedback and error reporting.

The recommended approach is to use the SCHEMACHECK=ONLY option first tovalidate the data, and thereafter to use the default SCHEMACHECK=NOwhenever loading the data into the directory.

The ACLCHECK environment variable specifies whether to process the ACLinformation contained in the ldif file. The default is YES.

Do not run bulkload while the directory server (slapd) is running.

In addition to the disk space required for data storage in the local databasedirectory, the bulkload tool requires temporary storage for data manipulationbefore inserting the data into the database. The default path for this temporarystorage is /tmp/ldapimport. You can change the path using the LDAPIMPORTenvironment variable:export LDAPIMPORT=/newpath

You must have write permission to this directory. You will need about 2.5 times thesize of the ldif file that is available in the LDAPIMPORT directory.

If you receive an error like the following:SQL3508N Error in accessing a file of type "SORTDIRECTORY" during loador load query. Reason code: "2". Path: "/u/ldapdb2/sqllib/tmp/".


then you should set the environment variable DB2SORTTMP to a directory (ordirectories) in a file system with more space to be utilized during the bulkload.Multiple directories can be specified separated by a comma (″,″) as in:export DB2SORTTMP=/sortdir1,/sortdir2

When running bulkload, inspect the output messages carefully. If errors occurduring execution, the directory might be incompletely populated. You might needto drop all the LDAP tables, or drop the database (re-create an empty database),and start over. If this happens, no data was added to the directory, and thebulkload should be attempted again. In addition, you might lose data when youdrop all the LDAP tables.

The file /usr/ldap/examples/sample.ldif includes sample data. You can use thedata in the file to experiment with populating a directory using the bulkload tool,or you can use the ldif2db command line utility. However, the ldif2db utilitymight be considerably slower than the bulkload utility for large amounts of data.

For performance reasons, the bulkload tool does not check for duplicate entries.Ensure that your input ldif file does not contain duplicate entries. If any duplicatesexist, remove the duplicate entries.

If bulkload fails at the ″DB2 LOAD″ phase, see the db2load.log file for the reasons.This log file is located on Windows NT in c:\tmp\ldapimport, on AIX in/tmp/ldapimport, and on Linux and Solaris in /var/ldap/ldapimport. (Ifenvironment variable LDAPIMPORT is defined, find the file in the directorydefined by the environment variable.) Correct the problem and rerun bulkload.Bulkload reloads the files from the last successful load consistency point.

When bulkload fails, the recovery information is stored in <installationdirectory>/etc/bulkload_status. This file is not removed until all of the data isloaded successfully. This helps insure the data integrity of the directory. If youdecide to reconfigure the database and start over, the bulkload_status file needs tobe removed manually or bulkload still tries to recover from the last successful loadpoint.

Alternative to bulkload for adding a large number of members toa groupIn most situations if you are performing a large number of updates at one time orif you are initializing the LDAP directory from a known, large set of users orgroups or both, use the bulkload utility. However, if you are working with a largegroup (approximately 10,000 members) or, in general, any LDAP entry containingan attribute with many values, you might want to use these alternative methods:

Adding a large number of members to a preexisting group: To add a largenumber of members to a group which already exists, use the ldapmodify utilitywith maximum increments of 10,000 users at a time. For example you can useldapmodify with the following:

dn: cn=biggroup,ou=epersonchangetype: modifyreplace: membermember: cn=firstuser,ou=eperson>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>dn: cn=biggroup,ou=epersonchangetype: modifyadd: membermember: cn=seconduser,ou=eperson


member: cn=thirduser,ou=eperson....member: cn=tenthousandthuser,ou=eperson

Adding a large number of members to a nonexisting group: To add a largenumber of members to a group that does not exist, use the ldapadd utility withmaximum increments of 10,000 users at a time. For example you can use ldapaddwith the following:

dn: cn=biggroup,ou=epersonobjectclass: topobjectclass: accessgroupcn: testgroupmember: cn=firstuser,ou=eperson>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>dn:cn=biggroup,ou=epersonchangetype: modifyadd: membermember: cn=seconduser,ou=epersonmember: cn=thirduser,ou=eperson....member: cn=tenthousandthuser,ou=eperson

Db2ldif utilityThis program is used to dump entries from a directory stored in a relationaldatabase into a text file in LDAP Directory Interchange Format (LDIF).

Synopsis:db2ldif -o <outputfile> [-s <subtree DN>]

Command Line Options:All options are case sensitive.

-o <outputfile>Specifies the LDIF output file to contain the directory entries inLDIF. All entries from the specified subtree are written in LDIF tothe output file. This option is required. If the file is not in thecurrent directory, a full path and file name must be specified.

-s <subtree DN>The subtree DN identifies the top entry of the subtree that is to bedumped to the LDIF output file. This entry, plus all below it in thedirectory hierarchy, are written out. If this option is not specified,all directory entries stored in the database are written to the outputfile based on the suffixes specified in the configuration file.

All other command line inputs result in a syntax error message, after which theproper syntax is displayed.


Chapter 5. Directory schema

The IBM SecureWay Directory (Version 3.2.2) includes dynamic schema support.The SLAPD Version 3.2.2 schema is published as part of the directory information,and is available in the Subschema entry (DN=″cn=schema″). You can query theschema using the ldap_search() API and modify it using ldap_modify(). See theIBM SecureWay Directory Client SDK Programming Reference for more informationabout these APIs.

SLAPD Version 3.2.2 has more configuration information than that included in theLDAP Version 3 RFCs (or standard specifications). For example, for a givenattribute, you can state which indexes must be maintained. This additionalconfiguration information is maintained in the subschema entry as appropriate. Anadditional object class is defined for the subschema entry IBMsubschema, whichhas ″MAY″ attributes that hold the extended schema information.

Common schema supportThe IBM SecureWay Directory supports standard directory schema as defined inthe following:v The Internet Engineering Task Force (IETF) LDAP Version 3.2 RFCs, such as RFC

1778, 2252 and 2256.v The Directory Enabled Network (DEN)v The Common Information Model (CIM) from the Desktop Management Task

Force (DMTF)v The Lightweight Internet Person Schema (LIPS) from the Network Application

Consortium

This version of LDAP includes the LDAP Version 3.2 defined schema in the defaultschema configuration. It also includes the DEN schema definitions as separate files,which can be added to the directory configuration as necessary.

IBM also provides a set of extended common schema definitions that other IBMproducts share when they exploit the LDAP directory. They include:v Objects for white page applications such as eperson, group, country,

organization, organization unit and role, locality, state, and so forthv Objects for other subsystems such as accounts, services and access points,

authorization, authentication, security policy, and so forth.

The subschema entriesThere is one subschema entry per SLAPD Version 3.2 server. All entries in thedirectory have an implied subschemaSubentry attribute type. The value of thesubschemaSubentry attribute type is the DN of the subschema entry thatcorresponds to the entry. All entries under the same server share the samesubschema entry, and their subschemaSubentry attribute type has the same value.The subschema entry has the hardcoded DN ’cn=schema’.

The subschema entry belongs to the object classes ’top’, ’subschema’, and’IBMsubschema’. The ’IBMsubschema’ object class has no MUST attributes and oneMAY attribute type (’IBMattributeTypes’).


http://www.ietf.org/

http://murchiso.com/den/

http://www.dmtf.org

http://www.dmtf.org

http://www.netapps.org/

http://www.netapps.org/

The IBMsubschema object classThe IBMsubschema object class is used only in the subschema entry as follows:( <objectClass-oid-TBD> NAME 'IBMsubschema' AUXILIARY

MAY IBMattributeTypes )

The IBMAttributeTypes attribute typeThe IBMAttributeTypes object class can be used to define schema information notcovered by the LDAP Version 3 standard for attributes known only to SLAPDversion 3.2. Values of IBMAttributeTypes must comply with the followinggrammar:IBMAttributeTypesDescription = "(" whsp

numericoid whsp[ "DBNAME" qdescrs ] ; at most 2 names (table, column)[ "ACCESS-CLASS" whsp IBMAccessClass whsp ][ "LENGTH" wlen whsp ] ; maximum length of attribute[ "EQUALITY" [ IBMwlen ] whsp ] ; create index for matching rule[ "ORDERING" [ IBMwlen ] whsp ] ; create index for matching rule[ "APPROX" [ IBMwlen ] whsp ] ; create index for matching rule[ "SUBSTR" [ IBMwlen ] whsp ] ; create index for matching rule[ "REVERSE" [ IBMwlen ] whsp ] ; reverse index for substringwhsp ")"

IBMAccessClass ="NORMAL" / ; this is the default"SENSITIVE" /"CRITICAL" /"RESTRICTED" /"SYSTEM" /"OBJECT"

IBMwlen = whsp len

NumericoidUsed to correlate the value in attributetypes with the value inIBMAttributeTypes.

DBNAMEYou can provide 2 names at the most, if indeed 2 names are given. Thefirst is the table name used for this attribute. The second is the columnname used for the fully normalized value of the attribute in the table. Ifyou provide only one name, it is used as the table name as well as thecolumn name. If you do not provide any DBNAMEs, then the shortattribute name is used (from the attributetypes).

ACCESS-CLASSThe access classification for this attribute type. If ACCESS-CLASS isomitted, it defaults to normal.

LENGTHThe maximum length of this attribute. The length is expressed as thenumber of bytes. SecureWay Directory Version 3.2.2 has a provision forspecifying the length of an attribute. In the attributetypes value, the string:( attr-oid ... SYNTAX syntax-oid{len} ... )

can be used to indicate that the attributetype with oid attr-oid has amaximum length.


EQUALITY, ORDERING, APPROX, SUBSTR, REVERSEIf any of these attributes are used, an index is created for thecorresponding matching rule. The optional length specifies the width of theindexed column. For many syntaxes, you can share a single index toimplement multiple matching rules. SLAPD Version 3.2 takes advantage ofthis. It assigns a length when one is not provided by the user. SLAPD canalso use a shorter length than what the user requested when it makessense to do so. For example, when the length of the index exceeds themaximum length of the attribute, the index length is ignored.

Schema file attribute typesSchema configuration provides values for the following attribute types:v objectClassesv attributesv matching rulesv ldap syntaxes

The syntax of these schema definitions is based on the LDAP Version 3 RFCs.

A sample configuration file could contain:objectclasses=( 1.3.6.1.4.1.1466.101.120.111

NAME 'extensibleObject'SUP top AUXILIARY )

objectclasses=( 2.5.20.1NAME 'subschema'AUXILIARY MAY

( dITStructureRules$ nameForms$ ditContentRules$ objectClasses$ attributeTypes$ matchingRules$ matchingRuleUse ) )

objectclasses=( 2.5.6.1NAME 'alias'SUP top STRUCTURALMUST aliasedObjectName )

attributeTypes {( 2.5.18.10 NAME 'subschemaSubentry' EQUALITY distinguishedNameMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATIONSINGLE-VALUE USAGE directoryOperation )

( 2.5.21.5 NAME 'attributeTypes'EQUALITY objectIdentifierFirstComponentMatchSYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )

( 2.5.21.6 NAME 'objectClasses'EQUALITY objectIdentifierFirstComponentMatchSYNTAX 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE directoryOperation )

}

ldapSyntaxes {( 1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary' )( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' )( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' )( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' )( 1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' )( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' )( 1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER' )

Chapter 5. Directory schema 63

( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' )( 1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' )

}

matchingRules {( 2.5.13.2 NAME 'caseIgnoreMatch'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )( 2.5.13.0 NAME 'objectIdentifierMatch'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 )}

As shown in the preceding example, it is not required that all of the attributevalues of a given attribute type be provided in a single production.

Schema queriesThe ldap_search() API can be used to query the subschema entry, as shown in thefollowing example:DN : "cn=schema"search scope : basefilter : objectclass=subschema or objectclass=*

This example retrieves the full schema. To retrieve all of the values of selectedattribute types, use the attrs parameter in ldap_search. You cannot retrieve only aspecific value of a specific attribute type.

See the IBM SecureWay Directory Version 3.2: Client SDK Programming Reference formore information about the ldap_search API.

Dynamic schema changesTo perform a dynamic schema change, use the ldap_modify API with a DN of″cn=schema″. It is permissible to add, delete, or replace only one schema entity (forexample, an attribute type or an object class) at a time.

To delete a schema entity, provide the oid in parentheses:( oid )

You can also provide a full description. In either case, the matching rule used tofind the schema entity to delete is objectIdentifierFirstComponentMatch.

To add or replace a schema entity, you MUST provide a LDAP Version 3 definitionand you MAY provide the IBM definition. In all cases, you must provide only thedefinition or definitions of the schema entity that you want to affect.

For example, to delete the attribute type ’cn’ (its OID is 2.5.4.3), use ldap_modify()with:

LDAPMod attr;LDAPMod *attrs[] = { &attr, NULL };char *vals [] = { "( 2.5.4.3 )", NULL };attr.mod_op = LDAP_MOD_DELETE;attr.mod_type = "attributeTypes";attr.mod_values = vals;ldap_modify_s(ldap_session_handle, "cn=schema", attrs);


To add a new attribute type bar with OID 20.20.20 that has a NAME of length 20chars:char *vals1[] = { "( 20.20.20 NAME 'bar' SUP NAME )", NULL };

char *vals2[] = { "( 20.20.20 LENGTH 20 )", NULL };LDAPMod attr1;LDAPMod attr2;LDAPMod *attrs[] = { &attr1, &attr2, NULL };attr1.mod_op = LDAP_MOD_ADD;attr1.mod_type = "attributeTypes";attr1.mod_values = vals1;attr2.mod_op = LDAP_MOD_ADD;attr2.mod_type = "IBMattributeTypes";attr2.mod_values = vals2;ldap_modify_s(ldap_session_handle, "cn=schema", attrs);

See the IBM SecureWay Directory Version 3.2: Client SDK Programming Reference formore information about the ldap_modify API.

Disallowed schema changesNot all schema changes are allowed. Change restrictions include the following:v Any change to the schema must leave the schema in a consistent state.v An attribute type that is a supertype of another attribute type may not be

deleted. An attribute type that is a ″MAY″ or a ″MUST″ attribute type of anobject class may not be deleted.

v An object class that is a superclass of another may not be deleted.v Attribute types or object classes that refer to nonexisting entities (for example,

syntaxes or object classes) cannot be added.v Attribute types or object classes cannot be modified in such a way that they end

up referring to nonexisting entities (for example, syntaxes or object classes).

Changes to the schema that affect the operation of SLAPD Version 3.2.2 are notallowed. See “Schema definitions that cannot be changed” on page 145 for a list ofthe schema object classes and attributes that cannot be deleted or modified.

Schema checkingWhen SLAPD Version 3.2 is initialized, the schema files are read and checked forconsistency and correctness. If the checks fail, SLAPD Version 3.2 fails to initializewith a proper error message. During any dynamic schema change, the resultingschema is also checked for consistency and correctness. If the checks fail, an erroris returned and the change fails. Some checks are part of the grammar (forexample, an attribute type can have at most one supertype, or an object class canhave any number of superclasses).

The following items are checked for attribute types:v Two different attribute types cannot have the same name or OID.v The inheritance hierarchy of attribute types does not have cycles.v The supertype of an attribute type must also be defined, although its definition

might be displayed later, or in a separate file.v If an attribute type is a subtype of another, they both have the same USAGE.v All attribute types have a syntax either directly defined or inherited.v Only operational attributes can be marked as NO-USER-MODIFICATION.v Only user attribute types can be collective.


v Collective attribute types cannot be single-valued.

The following items are checked for object classes:v Two different object classes cannot have the same name or OID.v The inheritance hierarchy of object classes does not have cycles.v The superclasses of an object class must also be defined, although its definition

might appear later or in a separate file.v The ″MUST″ and ″MAY″ attribute types of an object class must also be defined,

although its definition might appear later or in a separate file.v Every structural object class is a direct or indirect subclass of top.v If an abstract object class has superclasses, the superclasses must also be abstract.

Checking an entry against the schemaWhen an entry is added or modified through an LDAP operation, the entry ischecked against the schema. By default, all checks listed in this section areperformed. However, you can selectively disable some of them by providing avalue to the schemacheck configuration directive.

To comply with the schema an entry is checked for the following conditions:

With respect to object classes:

v Must have at least one value of attribute type ″objectClass″.v Can have any number of auxiliary object classes including zero. This is

not a check, but a clarification. There are no options to disable this.v Can have any number of abstract object classes, but only as a result of

class inheritance. This means that for every abstract object class that theentry has, it also has a structural or auxiliary object class that inheritsdirectly or indirectly from that abstract object class.

v Must have at least one structural object class.v Must have exactly one immediate or base structural object class. This

means that of all the structural object classes provided with the entry,they all must be superclasses of exactly one of them. The most derivedobject class is called the ″immediate″ or ″base structural″ object class ofthe entry, or simply the ″structural″ object class of the entry.

v Cannot change its immediate structural object class (on ldap_modify).v For each object class provided with the entry, the set of all of its direct

and indirect superclasses is calculated; if any of those superclasses is notprovided with the entry, then it is automatically added.

The validity of the attribute types for an entry is determined as follows:

v The set of MUST attribute types for the entry is calculated as the unionof the sets of MUST attribute types of all of its object classes, includingthe implied inherited object classes. If the set of MUST attribute typesfor the entry is not a subset of the set of attribute types contained by theentry, the entry is rejected.

v The set of MAY attribute types for the entry is calculated as the union ofthe sets of MAY attribute types of all of its object classes, including theimplied inherited object classes. If the set of attribute types contained bythe entry is not a subset of the union of the sets of MUST and MAYattribute types for the entry, the entry is rejected.

v If any of the attribute types defined for the entry are marked asNO-USER-MODIFICATION, the entry is rejected.


The validity of the attribute type values for an entry is determined as follows:

v For every attribute type contained by the entry, if the attribute type issingle-valued and the entry has more than one value, the entry isrejected.

v For every attribute value of every attribute type contained by the entry,if its syntax does not comply with the syntax checking routine for thesyntax of that attribute, the entry is rejected.

v For every attribute value of every attribute type contained by the entry,if its length is greater than the maximum length assigned to thatattribute type, the entry is rejected.

The validity of the DN is checked as follows:

v The syntax is checked for compliance with the BNF forDistinguishedNames. If it does not comply, the entry is rejected.

v The attribute types used in the RDN are subtypes of the attribute typeNAME. This is in accordance with X.520 section 5.2.1 where it is statedthat ″The Name attribute type is the attribute supertype from whichstring attribute types typically used for naming may be formed.″

v It is verified that the RDN is made up with only attribute types that arevalid for that entry.

v It is verified that the values of attribute types used in the RDN appearin the entry.

Access controlsDynamic configuration changes can be performed only by the master server (forreplication) and root.

ReplicationWhen a dynamic configuration change is performed, it is replicated just like anyother ldap_modify operation.

Netscape compatibilityThe parser used in the stand-alone LDAP daemon (SLAPD) version 3.2 allows theattribute values of schema attribute types (objectClasses and attributeTypes ) to bespecified using the Netscape grammar . For example, descrs and numeric-oids canbe specified with surrounding single quotation marks (as if they were qdescrs).However, the schema information is always made available through ldap_search.As soon as a single dynamic change (using ldap_modify) is performed on anattribute value in a file, the whole file is replaced by one where all attribute valuesfollow the SecureWay Directory Version 3.2.2 specifications. Because the parserused on the files and on ldap_modify requests is the same, an ldap_modify thatuses the Netscape grammar for attribute values is also handled correctly.

When a query is made on the subschema entry of a Netscape server, the resultingentry can have more than one value for a given object identifier (OID). Forexample, if a certain attribute type has two names (such as ’cn’ and’commonName’), then the description of that attribute type is provided twice, oncefor each name. SLAPD Version 3.2 can parse a schema where the description of asingle attribute type or object class appears multiple times with the samedescription (except for NAME and DESCR). However, when SLAPD Version 3.2publishes the schema it provides a single description of such an attribute type with


all of the names listed (the short name comes first). For example, here is howNetscape grammar describes the common name attribute:

( 2.5.4.3 NAME 'cn'DESC 'Standard Attribute'SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' )

( 2.5.4.3 NAME 'commonName'DESC 'Standard Attribute, alias for cn'SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' )

This is how SLAPD Version 3.2 describes it:( 2.5.4.3 NAME ( 'cn' 'commonName' ) SUP name )

SLAPD Version 3.2 supports subtypes. If you do not want ’cn’ to be a subtype ofname (which deviates from the standard), you can declare the following:( 2.5.4.3 NAME ( 'cn' 'commonName' )

DESC 'Standard Attribute'SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' )

The first name (’cn’) is taken as the preferred or short name and all other namesafter ’cn’ as alternate names. From this point on, the strings ’2.3.4.3’, ’cn’ and’commonName’ (as well as their case-insensitive equivalents) can be usedinterchangeably within the schema or for entries added to the directory.

Dynamic schemaIBM SecureWay Directory requires that the schema defined for a naming context bestored in a special directory entry, ″cn=schema″. The entry contains all of theschema defined for a suffix. To retrieve schema information, you can perform anldap_search by using the following:DN: "cn=schema", search scope: base, filter: objectclass=subschemaor objectclass=*

The schema contains the following information:

Object classA collection of attributes. A class can inherit attributes from one or moreparent classes.

Attribute typesContain information about the attribute, such as the name, oid, andmatching rules.

IBM attribute typesThe IBM LDAP directory implementation specific attributes, such asdatabase table name, column name, SQL type, and the maximum length ofeach attribute.

SyntaxesInclude the following:1.3.18.0.2.8.1 DESC 'IBM Attribute Type Description' )

1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN - distinguished name' )1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String - case-insensitive string' )1.3.6.1.4.1.1466.115.121.1.16 DESC 'DIT Content Rule Description' )1.3.6.1.4.1.1466.115.121.1.17 DESC 'DIT Structure Rule Description' )1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' )1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String - case-sensitive string' )1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER - integral number' )1.3.6.1.4.1.1466.115.121.1.3 DESC 'Attribute Type Description' )1.3.6.1.4.1.1466.115.121.1.30 DESC 'Matching Rule Description' )


1.3.6.1.4.1.1466.115.121.1.31 DESC 'Matching Rule Use Description' )1.3.6.1.4.1.1466.115.121.1.35 DESC 'Name Form Description' )1.3.6.1.4.1.1466.115.121.1.37 DESC 'Object Class Description' )1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' )1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary - octet string' )1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' )1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' )1.3.6.1.4.1.1466.115.121.1.54 DESC 'LDAP Syntax Description' )1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean - TRUE/FALSE' )

Matching rulesInclude the following:MatchingRules= ( 2.5.13.5 NAME 'caseExactMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.1.26 )MatchingRules= ( 2.5.13.2 NAME 'caseIgnoreMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )MatchingRules= ( 2.5.13.7 NAME 'caseExactSubstringsMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )MatchingRules= ( 2.5.13.6 NAME 'caseExactOrderingMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )MatchingRules= ( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )MatchingRules= ( 2.5.13.3 NAME 'caseIgnoreOrderingMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )MatchingRules= ( 1.3.18.0.2.4.405 NAME 'distinguishedNameOrderingMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 )MatchingRules= ( 2.5.13.1 NAME 'distinguishedNameMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 )MatchingRules= ( 2.5.13.28 NAME 'generalizedTimeOrderingMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 )MatchingRules= ( 2.5.13.27 NAME 'generalizedTimeMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 )MatchingRules= ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )MatchingRules= ( 1.3.6.1.4.1.1466.109.114.1 NAME 'caseExactIA5Match' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )MatchingRules= ( 2.5.13.29 NAME 'integerFirstComponentMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )MatchingRules= ( 2.5.13.14 NAME 'integerMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )MatchingRules= ( 2.5.13.17 NAME 'octetStringMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 )MatchingRules= ( 2.5.13.0 NAME 'objectIdentifierMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )MatchingRules= ( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )MatchingRules= ( 2.5.13.21 NAME 'telephoneNumberSubstringsMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 )MatchingRules= ( 2.5.13.20 NAME 'telephoneNumberMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 )MatchingRules= ( 2.5.13.25 NAME 'uTCTimeMatch' \

SYNTAX 1.3.6.1.4.1.1466.115.121.1.53 )

The schema information can be modified through the ldap_modify API. Consultthe Client SDK Programming Reference for additional information. With the DN″cn=schema″ you can add, delete or replace an attribute type or an object class. Todelete a schema entity, provide the oid in parenthesis (oid). You also can provide afull description. Add or replace a schema entry with the LDAP Version 3.1definition or with the IBM attribute extension definition or with both definitions.


SubclassingThis version of the IBM SecureWay Directory Server supports object inheritance forobject class and attribute definitions. A new object class can be defined with parentclasses (multiple inheritance) and the additional or changed attributes.

Schema update operations are checked against the schema class hierarchy forconsistency before being processed and committed.

DEN schema supportThe Directory-Enabled Network (DEN) specification defines a standard schemaform that stores and describes the relationships among objects that represent users,applications, network elements, and networking services.

To support DEN, the IBM SecureWay Directory server provides the followingfeatures:v Subclassing (class inheritance). Class definitions can be created from existing

definitions through subclassing. The new class definition inherits the propertiesfrom the parent class definition. The SUP option in the object class definition isused to specify the parent (or superior) object classes.

v LDAP syntaxes required by DEN, which include the following:– Boolean– DN– Directory String– Generalized Time– UTC Time– IA5 String– Integer

Generalized and UTC timeThere are different notations used to designate date and time-related information.For example, the fourth day of February in the year 1999 can be written as:2/4/994/2/9999/2/44.2.199904-FEB-1999

as well as many other notations.

IBM SecureWay Directory Server standardizes the timestamp representation byrequiring the LDAP servers to support two syntaxes:v The Generalized Time syntax, which takes the form:

YYYYMMDDHHMMSS[.|,fraction][(+|-HHMM)|Z]

There are 4 digits for the year, 2 digits each for the month, day, hour, minute,and second, and an optional fraction of a second. Without any further additions,a date and time is assumed to be in a local time zone. To indicate that a time ismeasured in Coordinated Universal Time, append a capital letter Z to a time ora local time differential. For example:"19991106210627.3"


which in local time is 6 minutes, 27.3 seconds after 9 p.m. on 6 November 1999."19991106210627.3Z"

which is the coordinated universal time."19991106210627.3-0500"

which is local time as in the first example, with a 5 hour difference in relation tothe coordinated universal time.

If you designate an optional fraction of a second, a period or a comma isrequired. For local time differential, a ’+’ or a ’-’ must precede the hour-minutevalue

v The Universal time syntax, which takes the form:YYMMDDHHMM[SS][(+ | -)HHMM)|Z]

There are 2 digits each for the year, month, day, hour, minute, and optionalsecond fields. As in GeneralizedTime, an optional time differential can bespecified. For example, if local time is a.m. on 2 January 1999 and thecoordinated universal time is 12 noon on 2 January 1999, the value of UTCTimeis either:"9901021200Z"

or"9901020700-0500"

If the local time is a.m. on 2 January 2001 and the coordinated universal time is12 noon on 2 January 2001, the value of UTCTime is either:"0101021200Z"

or"0101020700-0500"

UTCTime allows only 2 digits for the year value, therefore the usage is notrecommended.

The supported matching rules are generalizedTimeMatch for equality andgeneralizedTimeOrderingMatch for inequality. Substring search is not allowed. Forexample, the following filters are valid:generalized-timestamp-attribute=199910061030utc-timestamp-attribute>=991006generalized-timestamp-attribute=*

The following filters are not valid:generalized-timestamp-attribute=1999*utc-timestamp-attribute>=*1010


Chapter 6. IBM SecureWay Directory Management Tool

The IBM SecureWay Directory Management Tool provides a graphical userinterface that enables you to manage information stored in directory servers. Usethe tool to:v Connect to one or more directory servers using SSL or non-SSL connectionsv Display server properties and rebind to the serverv List, add, edit, and delete schema attributes and object classesv List, add, edit, and delete directory entriesv Modify directory entry access control lists (ACLs)v Search the directory tree

Starting and configuringThe Directory Management Tool is a part of the client package of the IBMSecureWay Directory Version 3.2.2 product.

Note: At the present time the Directory Management Tool has a directorylimitation of 100,000 entries. Using the tool with directories having greaterthan 100,000 entries might lessen the performance of the tool.

Starting the Directory Management ToolTo start the tool, type dmt in a new command window.

Note: When you start the Directory Management Tool , the tool might hang. Toavoid this problem you can set the environment variable DISPLAY to<hostname>:0.0. For example:export DISPLAY=berry:0.0

The dmt command has two optional parameters:

-f The -f flag overrides the default dmt.conf configuration file and speficiesthe fully qualified path and filename of another configuration file. You canconfigure the tool to automatically connect to one or more servers and tolog in particular Distinguished Names (DNs) when it is started, forexample,dmt -f c:\temp\dmtservers.conf

-k The -k flag specifies the path to the keyclass file, for example,dmt -k c:\keys

Note: If you are using Windows NT, you can also start the tool from the Startmenu (Start-->Programs-->IBM SecureWay Directory-->DirectoryManagement Tool).

Configuring the Directory Management ToolTo configure the Directory Mangement Tool, edit the configuration file located atLDAP/etc/dmt.conf. For example, if you edit the file to contain these lines:


server1.url=ldap://ldapsrv.austin.ibm.com:389server1.security.bindDN=cn=adminserver1.security.password=secretserver1.security.ssl.keyclass=

When started, the tool connects to the non-SSL port 389 of a directory server atmachine ldapsrv.austin.ibm.com. It logs in to the server as DN: cn=admin usingpassword secret.

Multiple servers can be specified in the configuration file. For example using anSSL port:

server2.url=ldaps://localhost.austin.ibm.com:636server2.security.bindDN=cn=adminserver2.security.password=secretserver2.security.ssl.keyclass=localhost

If you do not want to keep a clear password in the configuration file in anunprotected directory, leave the principal name empty to perform an initial bind tothe server as an anonymous user, then rebind with the correct DN. If the tool isstarted without default servers and login users defined in the configuration file,use the Add server button to add servers. If Secure Socket Layer (SSL) is used,specify the proper keyclass file. The keyclass file contains certificate information.

Note: If SSL is used, you must have the GSKIT package installed.

After the tool has been started, the application window has four parts:

Navigation areaThe navigation area displays expandable categories for various servercontent tasks.

Server tabsTabs for connected servers are displayed at the top of the navigation areaallowing management of multiple directory servers from a single interface.

Work areaThe work area displays the tasks associated with the selected task in thenavigation area. For example, if Browse tree is selected in the navigationarea, the work area displays the directory tree and a toolbar containingtasks related to working with directory entries.

Status areaThe status area, located at the top of the work area, contains the title of theselected task, system messages, and a link to the help.

Working with serversYou can use the Directory Management Tool to:v Connect to a serverv Add a serverv Delete a serverv View server propertiesv View server statusv Launch Server Administration


Connecting to a serverWhen the Directory Management Tool is started, connections are made to theservers specified in the configuration file. If a directory User DN and password arenot provided in the Directory Management Tool configuration file, the connectionto the server is anonymous. Anonymous users can browse the directory tree andschema, but in most instances can not perform directory updates.

Adding a User DN and password to the configuration file enables you to connectto the specified server as the specified user every time you launch the DirectoryManagement Tool. The default configuration file is <ldap>/etc/dmt.conf.

For example, adding:server1.url=ldap://test.ibm.com:389server1.security.bindDN=cn=rootserver1.security.password=secret

to dmt.conf connects to the server test.ibm.com as user cn=root with the passwordsecret.

To reconnect to an already connected server as a different user,1. If you have not already done so, expand the Server category in the navigation

area, then click Rebind.2.

v For an anonymous connection, select Anonymous.v For an Authenticated connection:

a. Select Authenticated.b. Enter the User DN and User password.

Note: The User DN is the distinguished name used for access to thedirectory server, for example, cn=John Doe, o=IBM, c=US. TheUser password is the password associated with that User DN.

v Click OK.

If you select Authenticated but do not enter a User DN, the connection defaults toAnonymous.

Viewing server statusTo view the server status, expand the Server category in the navigation area, thenclick Status.

The status panel displays:v The version of SecureWay Directoryv The total and maximum number of connections, as well as the number of

current connections.v The total number of threads, as well as the number of threads blocked on read

or write.v The number of entries sent.v The current time on the server.v The time the server was last started.v The number of operations initiated and the number of operations completed.

Chapter 6. IBM SecureWay Directory Management Tool 75

Viewing server propertiesIf you have not done so already, expand the Server category in the navigation area,then click Properties.

The current bind DN, subschema entry, supported LDAP protocol versions, andthe naming contexts that the server holds are displayed.

Adding a serverThe Directory Management Tool displays servers as tabs at the top of thenavigation area. Each tab displays the name of the associated directory server andan icon to idicate if the server is a:

v Master server

v Replica server

v Peer server

To add a new server, click Add server at the bottom of the navigation area.1. Enter the Server name. Use either the IP address in quadruple format, for

example, 9.53.92.149, or the domain name in the format hostname.domainname,for example, test.austin.ibm.com.

2. Enter the required Port for the server.Depending upon whether you are connecting to the server using Secure SocketsLayer (SSL) and the type of authentication you select, you are prompted foradditonal information.

Note: To use SSL, ensure that you have started the Directory Management Toolwith the -k option.

If you want to connect to the server using SSL:a. Select the Use SSL checkbox.b. Enter the Certificate name used to authenticate the client.c. Select an Authentication type

v If you select None orSASL External:1) Enter the Keyclass filename that is required for using SSL. Do not

include the .class extension in the file name.2) Enter the Keyclass file password used to access the key database.

v If you select Simple or CRAM MD5:1) Enter the User DN used to connect to the server. If no User DN is

specified, the connection is anonymous.2) Enter the User Password to provide access to the server if you

specified a User DN.3) Enter the Keyclass filename that is required for using SSL. Do not

include the .class extension in the file name.4) Enter the Keyclass file password used to access the key database.

If you are not going to connect to the server using SSL:a. Select an Authentication type

v If you select None, no additional information is required on this panel.


Note: SASL EXTERNAL is not available without SSL.v If you select Simple or CRAM MD5:

1) Enter the User DN used to connect to the server. If no User DN isspecified, the connection is anonymous.

2) Enter the User Password to provide access to the server if youspecified a User DN.

3. Click OK to add the server, if you selected an authentication of none or simpleyou can click Save to save the server information to the dmt.conf file, or clickCancel to return to Browse tree without saving changes. To make changes to anexisting server, delete the server, then add a new server with the updatedinformation.

Deleting a serverThe Directory Management Tool displays server as tabs at the top of the navigationarea. Each tab displays the name of the associated directory server. To delete aserver:1. Click Delete server at the bottom of the navigation area.2. Select a server to delete. Delete multiple servers using the Ctrl key.3. Click Delete to delete the selected servers.

Using server administrationIBM SecureWay Directory Server Administration is a web-based interface throughwhich you can setup and maintain an LDAP server and its backend database.

If you have not already done so, expand the Server category in the navigation area.1. Click Administration.2. Select a Web server protocol.

v Select http for an unsecure web server.v Select https for a secure web server.

3. Enter the Web server name in the format hostname.domainname, for example,testserver.ibm.com.

4. Enter the Web server port. Unless a port is specified, the default port is 80.5. Click OK. A Web browser launches with the Web address of the Server

Administration interface for the selected server. Consult the logon help foradditional information.

6. Enter the Admin ID created during LDAP configuration, for example, cn=root.7. Enter the Password associated with the Admin ID.8. Click Logon.

Using the toolbarThree tasks display a toolbar at the top of the work area. The toolbar, by default,displays icons and text. You can modify the toolbar settings to display only iconsor only text by editing the configuration file. The default configuration file isdmt.conf.

To edit the configuration file:1. Open the configuration file in a text editor.


2. Change the value of toolbar to either icon to display only icons or text todisplay only text. The default value for toolbar is both, which displays text andicons.

3. Save and close the configuration file.4. You must restart the directory management tool for the changes to take effect.

The toolbar contains a series of icons depending on the task selected in thenavigation area.

The Browse tree toolbar displays:

v - Click the Search icon to search the directory tree.

v - Click the Expand icon to expand all entries in the selected section of thedirectory tree.

v - Click the Add icon to add a directory entry beneath the selected entry.

v - Click the Edit icon to edit the selected entry.

v - Click the Duplicate icon to add a new entry with the attributes of theselected entry.

v - Click the Delete icon to delete the selected entry.

v - Click the ACLs icon to add or edit an Access Control List (ACL) to theselected directory entry.

v - Click the Edit RDN icon to edit the relative distinguished name of theselected entry.

v - Click the Add auxiliary class icon to add an auxiliary class to theselected entry.

The View object classes toolbar displays:

v - Click the Search icon to search for an object class..

v - Click the Add icon to add an object class.

v - Click the Edit icon to edit the selected object class.

v - Click the Delete icon to delete the selected object class.


The View object classes toolbar also contains a Sort by drop-down list. The defaultsort order for object classes is by object class name. You can also sort by:

InheritanceTo sort by inheritance based on Superior object class.

Type To sort by object class type (structural, auxiliary, or abstract).

The View attributes toolbar displays:

v - Click the Search icon to search for an attribute.

v - Click the Add icon to add an attribute.

v - Click the Edit icon to edit the selected attribute.

v - Click the Delete icon to delete the selected attribute.

The View attributes toolbar also contains a Sort by drop-down list. The defaultsort order for attributes is by attribute name. You can sort by:

SyntaxTo sort by attribute syntax, for example, to display all the attributes thatuse the Binary syntax.

AssociationTo sort by which object classes use specific attributes.

InheritanceTo sort by inheritance based on Superior attribute.


Chapter 7. Access Control Lists

Access Control Lists (ACL) provide a means to protect information stored in aLDAP directory. Administrators use ACLs to restrict access to different portions ofthe directory, or specific directory entries. LDAP directory entries are related toeach other by a hierarchical tree structure. Each directory entry (or object) containsthe distinguished name of the object as well as a set of attributes and theircorresponding values.

The object attributes associated with access control, such as owner,ownerSource,ownerPropagate, acl, aclSource and aclPropagate are unusual in thatthey are logically associated with each object, but can have values that dependupon other objects higher in the tree. Depending upon how they are established,these attribute values can be explicit to an object or inherited from an ancestor.

The access control model defines two sets of attributes: The Access ControlInformation (ACI) and the entryOwner Information. The ACI specifically defines asubject’s permission to perform a given operation against certain LDAP objects.The entryOwner information controls which subjects can define the ACIs. TheentryOwnership also acquires full access rights to the target object.

Using Access Control Information (ACI), administrators can restrict access todifferent portions of the directory, specific directory entries and, based on theattribute name or attribute access class, the attributes contained in the entries. Eachentry within the LDAP directory has a set of associated ACI. In conformance withthe LDAP model,the ACI and entryOwner informationis represented asattribute-value pairs. Furthermore, the ldif syntax is used to administer thesevalues. The attributes are:v aclEntryv aclPropagatev entryOwnerv ownerPropagate

The Access Control Attribute SyntaxEach of these attributes can be managed using LDIF notation. The followingdefines the syntax for the ACI and entryOwner attributes using BNF.<aclEntry> ::= <subject> [ ":" <rights> ]

<aclPropagate> ::= "true" | "false"

<entryOwner> ::= <subject>

<ownerPropagate> ::= "true" | "false"

<subject> ::= <subjectDnType> ':' <subjectDn> | <pseudoDn>

<subjectDnType> ::= "role" | "group" | "access-id"

<subjectDn> ::= <DN>

<DN> ::= distinguished name as described in RFC 2251, section 4.1.3.

<pseudoDn> ::= "group:cn=anybody" | "group:cn=authenticated" | "access-id:cn=this"


<rights> ::= <accessList> [":" <rights> ]

<accessList> ::= <objectAccess> | <attributeAccess> | <attributeClassAccess>

<objectAccess> ::= "object:" [<action> ":"] <objectPermissions>

<action> ::= "grant" | "deny"

<objectPermisssions> ::= <objectPermission> [ <objectPermissions> ]

<objectPermission> ::= "a" | "d" | ""

<attributeAccess> ::= "at." <attributeName> ":" [<action> ":"] <attributePermissions>

<attributeName> ::= attributeType name as described in RFC 2251, section 4.1.4. (OID oralpha-numeric string with leading alphabet, "-" and ";" allowed)

<attributePermissions> ::= <attributePermission> [<attributePermissions>]

<attributePermission> ::= "r" | "w" | "s" | "c" | ""

<attributeClassAccess> ::= <class> ":" [<action> ":"] <attributePermissions>

<class> ::= "normal" | "sensitive" | "critical"

AclEntry

SubjectA subject (the entity requesting access to operate on an object) consists of thecombination of a DN (Distinguished Name) type and a DN. The valid DN typesare: access Id, Group and Role.

The DN identifies a particular access-id, role or group. For example, a subjectmight be access-id: cn=personA, o=IBM or group: cn=deptXYZ, o=IBM.

Because the field delimiter is the colon (’:’), a DN containing colon(s) must bedouble-quoted. And a double-quoted DN must escape any double-quote sign withthe escape character ’\’, should it be present in the DN.

All directory groups can be used in access control.

Note: Version 3.1 and earlier LDAP servers restricted Groups which are to be usedin access control to have an objectclass of AccessGroup. This restriction islifted at Version 3.2. Any group of AccessGroup, GroupOfNames or’GroupofUniqueNames’ objectclasses can be used for access control.

Another DN type used within the access control model is role. While roles andgroups are similar in implementation, conceptually they are different. When a useris assigned to a role, there is an implicit expectation that the necessary authorityhas already been set up to perform the job associated with that role. With groupmembership, there is no built in assumption about what permissions are gained (ordenied) by being a member of that group.

Roles are similar to groups in that they are represented in the directory by anobject. Additionally, roles contain a group of DNs. Roles that are used in accesscontrol must have an objectclass of AccessRole.


Pseudo DNThe LDAP directory contains several pseudo DNs. These are used to refer to largenumbers of DNs which at bind time share a common characteristic, in relation toeither the operation being performed, or the target object on which the operation isbeing performed.

Currently, three pseudo DNs are defined:

group:cn=anybodyRefers to all subjects, including those that are unauthenticated. All usersbelong to this group automatically.

group:cn=authenticatedRefers to any DN which has been authenticated to the directory. Themethod of authentication is not considered.

access-id:cn=thisRefers to the bindDn which matches the target object’s DN on which theoperation is performed.

RightsAccess rights can apply to an entire object or to attributes of the object. The LDAPaccess rights are discrete. One right does not imply another right. The rights maybe combined together to provide the desired rights list following a set of rulesdiscussed later. Rights can be of null value, which indicates that no access rightsare granted to the subject on the target object. The rights consist of three parts:

Action:Defined values are grant or deny. If this field is not present, the default isset to grant.

Permission:There are six basic operations that may be performed on a directory object.From these operations, the base set of ACI permissions are taken. Theseare: add an entry, delete an entry, read an attribute value, write an attributevalue, search for an attribute, and compare an attribute value.

The possible attribute permissions are : read ( r ), write ( w ), search ( s ),and compare ( c ). Additionally, object permissions apply to the entry as awhole. These permissions are add child entries ( a ) and delete this entry (d ).

The following table summarizes the permissions needed to perform each ofthe LDAP operations.

Table 6.

Operation Permission Needed

ldapadd add (on parent)

ldapdelete delete (on object)

ldapmodify write (on attributes being modified)

Chapter 7. Access Control Lists 83


ldapsearch v search, read (on attributes in RDN)

v search (on attributes specified in thesearch filter)

v search (on attributes returned with justnames)

v search, read (on attributes returned withvalues)

ldapmodrdn write (on RDN attributes)

ldapcompare compare (on compared attribute)

Note: For search operations, the subject is required to have search (s)access to all the attributes in the search filter or no entries arereturned. For returned entries from a search, the subject is requiredto have search (s) and read (r) access to all the attributes in the RDNof the returned entries or these entries are not returned.

Access Target:These permissions can be applied to the entire object (add entry, deleteentry), to an individual attribute within the entry, or can be applied togroups of attributes (Attribute Access Classes) as described in thefollowing.

Attributes requiring similar permissions for access are grouped together inclasses. Attributes are mapped to their attribute classes in the directoryschema file. These classes are discrete; access to one class does not implyaccess to another class. Permissions are set with regard to the attributeaccess class as a whole. The permissions set on a particular attribute classapply to all attributes within that access class unless the individualattribute access permissions are specified.

IBM defines three attribute classes that are used in evaluation of access touser attributes: normal, sensitive, and critical. For example, attributecommonName falls into the normal class, and attribute userpasswordbelongs to the critical class. User defined attributes belong to the normalaccess class unless otherwise specified.

Two other access classes are also defined: system and restricted. Thesystem class attributes are creatorsName, modifiersName,createTimestamp, modifyTimestamp, ownerSource and aclSource. Theseare attributes maintained by the LDAP server and read only to thedirectory users. OwnerSource and aclSource are described in thePropagation section. The attributes that define the access control, namelyaclEntry, aclPropagate, entryOwner and ownerPropagate, are in therestricted class. All users have read access to the restricted attributes butonly entryOwners can create, modify, and delete these attributes.

EntryOwnerThe entry owners have complete permissions to perform any operation on theobject regardless of the aclEntry. Additionally, the entry owners are the only oneswho are permitted to administer the aclEntries for that object. EntryOwner is anaccess control subject, it can be defined as individuals, groups or roles.


Note: The directory administrator is one of the entryOwners for all objects in thedirectory by default, and the directory administrator’s entryOwnership cannot be removed from any object.

PropagationEntries on which an aclEntry has been placed are considered to have an explicitaclEntry. Similarly, if the entryOwner has been set on a particular entry, that entryhas an explicit owner. The two are not intertwined, an entry with an explicit ownermay or may not have an explicit aclEntry, and an entry with an explicit aclEntrymight have an explicit owner. If either of these values is not explicitly present onan entry, the missing value is inherited from an ancestor node in the directory tree.

Each explicit aclEntry or entryOwner applies to the entry on which it is set.Additionally, the value might apply to all descendants that do not have anexplicitly set value. These values are considered propagated; their values propagatethrough the directory tree. Propagation of a particular value continues untilanother propagating value is reached.

AclEntry and entryOwner can be set to apply to just a particular entry with thepropagation value set to ″false″, or an entry and its subtree with the propagationvalue set to ″true″. Although both aclEntry and entryOwner can propagate, theirpropagation is not linked in anyway.

The aclEntry and entryOwner attributes allow multi-values, however, thepropagation attributes (aclPropagate and ownerPropagate) can only have a singlevalue for all aclEntry or entryOwner attribute values within the same entry.

The system attributes aclSource and ownerSource contain the DN of the effectivenode from which the aclEntry or entryOwner are evaluated, respectively. If nosuch node exists, the value default is assigned.

An object’s effective access control definitions can be derived by the followinglogic:v If there is a set of explicit access control attributes at the object, then that is the

object’s access control definition.v If there is no explicitly defined access control attributes, then traverse the

directory tree upwards until an ancestor node is reached with a set ofpropagating access control attributes.

v If no such ancestor node is found, the default access described below is grantedto the subject.

Access EvaluationAccess for a particular operation is granted or denied based on the subject’s bindDN for that operation on the target object. Processing stops as soon as access canbe determined.

The checks for access are done by first finding the effective entryOwnership andACI definition, checking for entry ownership, and then by evaluating the object’sACI values.

By default, the directory administrator and the master server (for replication) getfull access rights to all objects in the directory except write access to systemattributes. Other entryOwners get full access rights to the objects under their


ownership except write access to system attributes. All users have read accessrights to system and restricted attributes. These predefined rights cannot bealtered. If the requesting subject has entryOwnership, access is determined by theabove default settings and access processing stops.

If the requesting subject is not an entryOwner, then the ACI values for the objectentries are checked. The access rights as defined in the ACIs for the target objectare calculated by the specificity and combinatory rules.

Specificity RuleThe most specific aclEntry definitions are the ones used in the evaluationof permissions granted/denied to a user. The levels of specificity are:v Access-id is more specific than group or role. Groups and roles are on

the same level.v Within the same dnType level, individual attribute level permissions are

more specific than attribute class level permissions.v Within the same attribute or attribute class level, deny is more specific

than grant.

Combinatory RulePermissions granted to subjects of equal specificity are combined. If theaccess cannot be determined within the same specificity level, the accessdefinitions of lesser specific level are used. If the access is not determinedafter all defined ACIs are applied, the access is denied.

Note: After a matching access-id level aclEntry is found in accessevaluation, the group level aclEntries are not included in accesscalculation. The exception is that if the matching access-id levelaclEntries are all defined under cn=this, then all matching grouplevel aclEntries are also combined in the evaluation.

In other words, within the object entry, if a defined ACI entry contains an access-idsubject DN that matches the bind DN, then the permissions are first evaluatedbased on that aclEntry. Under the same subject DN, if matching attribute levelpermissions are defined, they supersede any permissions defined under theattribute classes. Under the same attribute or attribute class level definition, ifconflicting permissions are present, denied permissions override grantedpermissions.

Note: A defined null value permission prevents the inclusion of less specificpermission definitions.

If access still can not be determined and all found matching aclEntries are definedunder ″cn=this″, then group membership is evaluated. If a user belongs to morethan one groups, the user receives the combined permissions from these groups.Additionally, the user automatically belongs to the cn=Anybody group andpossibly the cn=Authenticated group if the user did an authenticated bind. Ifpermissions are defined for those groups, the user receives the specifiedpermissions.

Note: Group and Role membership is determined at bind time and last until eitheranother bind takes place, or until an unbind request is received. Nestedgroups and roles, that is a group or role defined as a member of anothergroup or role, are not resolved in membership determination nor in accessevaluation.


For example, assume attribute1 is in the sensitive attribute class, and usercn=Person A, o=IBM belongs to both group1 and group2 with the followingaclEntries defined:1. aclEntry: access-id: cn=Person A, o=IBM: at.attributel:grant:rsc:sensitive:deny:rsc2. aclEntry: group: cn=group1,o=IBM:critical:deny:rwsc3. aclEntry: group: cn=group2,o=IBM:critical:grant:r:normal:grant:rsc

This user gets:v Access of ’rsc’ to attribute1, (from 1. Attribute level definition supersedes

attribute class level definition).v No access to other sensitive class attributes in the target object, (from 1).v No other rights are granted (2 and 3 are NOT included in access evaluation).

For another example, with the following aclEntries:1. aclEntry: access-id: cn=this: sensitive2. aclEntry: group: cn=group1,o=IBM:sensitive:grant:rsc:normal:grant:rsc

The user has:v no access to sensitive class attributes, (from 1. Null value defined under

access-id prevents the inclusion of permissions to sensitive class attributes fromgroup1).

v and access of ’rsc’ to normal class attributes (from 2).

Defining the ACIs and Entry OwnersThe following two examples show an administrative subdomain being established.The first example shows a single user being assigned as the entryOwner for theentire domain. The second example shows a group assigned as the entryOwner.

entryOwner: access-id:cn=Person A,o=IBMownerPropagate: true

entryOwner: group:cn=System Owners, o=IBMownerPropagate: true

The next example shows how a group ″cn=Dept XYZ, o=IBM″ is being givenpermissions to read, search and compare attribute1. The permission applies to theentire subtree below the node containing this ACI.

aclEntry: group:cn=Dept XYZ,o=IBM:at.attribute1:grant:rscaclPropagate: true

The next example shows how a role ″cn=System Admins,o=IBM″ is being givenpermissions to add objects below this node, and read, search and compareattribute2 and the critical attribute class. The permission applies only to the nodecontaining this ACI.aclEntry: role:cn=System Admins,o=IBM:object:grant:a:at.attribute2:grant:rsc:critical:grant:rscaclPropagate: false

Modifying the ACI and Entry Owner ValuesModify-replace

Modify-replace works the same way as all other attributes. If the attributevalue does not exist, create the value. If the attribute value exists, replacethe value.

Given the following ACIs for an entry:


aclEntry: group:cn=Dept ABC,o=IBM:normal:grant:rscaclPropagate: true

perform the following change:dn: cn=some entrychangetype: modifyreplace: aclEntryaclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rsc

The resulting ACI is:aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rscaclPropagate: true

ACI values for Dept ABC are lost through the replace.

Modify-addDuring an ldapmodify-add, if the ACI or entryOwner does not exist, theACI or entryOwner with the specific values is created. If the ACI orentryOwner exists, then add the specified values to the given ACI orentryOwner. For example, given the ACI:aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rsc

with a modification:dn: cn=some entrychangetype: modifyadd: aclEntryaclEntry: group:cn=Dept ABC,o=IBM:at.attribute1:grant:rsc

would yield an multi-valued aclEntry of:aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rscaclEntry: group:cn=Dept ABC,o=IBM:at.attribute1:grant:rsc

The permissions under the same attribute or attribute class are consideredas the basic building blocks and the actions are considered as thequalifiers. If the same permission value is being added more than once,only one value is stored. If the same permission value is being added morethan once with different action values, the last action value is used. If theresulting permission field is empty (″″), this permission value is set to nulland the action value is set to grant.

For example, given the following ACI:aclEntry: group:cn=Dept XYZ,O=IBM:normal:grant:rsc

with a modification:dn: cn=some entrychangetype: modifyadd: aclEntryaclEntry: group:cn=Dept XYZ,o=IBM:normal:deny:r:critical:deny::sensitive:grant:r

yields an aclEntry of:aclEntry: group:cn=Dept XYZ,O=IBM:normal:grant:sc:normal:deny:r:critical:grant::sensitive:gra

Modify-deleteTo delete a particular ACI value, use the regular ldapmodify-delete syntax.

Given an ACI of:aclEntry: group:cn=Dept XYZ,o=IBM:object:grant:adaclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rwsc


dn: cn = some entrychangetype: modifydelete: aclEntryaclEntry: group:cn=Dept XYZ,o=IBM:object:grant:ad

yields a remaining ACI on the server ofaclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rwsc

Deleting an ACI or entryOwner value that does not exist results in anunchanged ACI or entryOwner and a return code specifying that theattribute value does not exist.

Deleting the ACI/Entry Owner ValuesWith the ldapmodify-delete operation, the entryOwner can be deleted byspecifyingdn: cn = some entrychangetype: modifydelete: entryOwner

In this case, the entry would then have no explicit entryOwner. TheownerPropagate is also removed automatically. This entry would inherit itsentryOwner from the ancestor node in the directory tree following the propagationrule.

The same can be done to delete aclEntry completely:dn: cn = some entrychangetype: modifydelete: aclEntry

Deleting the last ACI or entryOwner value from an entry is not the same asdeleting the ACI or entryOwner. It is possible for an entry to contain an ACI orentryOwner with no values. In this case, nothing is returned to the client whenquerying the ACI or entryOwner and the setting propagates to the descendentnodes until it is overridden. To prevent dangling entries that nobody can access,the directory administrator always has full access to an entry even if the entry hasa null ACI or entryOwner value.

Retrieving the ACI/Entry Owner ValuesThe effective ACI or entryOwner values can be retrieved by simply specifying thedesired ACL or entryOwner attributes in a search, for example,ldapsearch -b "cn=object A, o=ibm" -s base "objectclass=*"

aclentry aclpropagate aclsource entryowner ownerpropagate ownersource

returns all ACL or entryOwner information that is used in access evaluation onobject A. Note that the returned values might not look exactly the same as they arefirst defined. The values are the equivalent of the original form.

Working with Access Control ListsFollow these steps to use the Directory Management Tool utility to work withACLs.1. If you have not done so already, expand the Directory tree category in the

navigation area, then click Browse tree.2. Select a directory entry. For example, cn=John Doe,ou=Advertising,o=ibm,c=US.


3. Click the ACL icon on the toolbar.

An entry can either have an explicitly defined ACL or inherit an ACL from aparent object.

The ACL panel contains two tabs:v ACLsv Owners

After modifying the settings on the ACLs and Owners tabs, click OK to add theACL to the selected entry.

The ACLs tab contains four sections:v The DN entry section displays:

– ACL source - The ACL source is the source of current ACL for the selectedentry. If the entry does not have an ACL, it inherits an ACL from parentobjects based on the ACL settings of the parent objects.

– Select either:- Inherit from ACL source - to inherit ACLs from the ACL source. In the

example used above, cn=John Doe,ou=Advertising,o=IBM,c=US inheritsfrom ou=Advertising,o=IBM,c=US

Note: If this option is selected, and you modify the Rights or Securityclass, you are modifying the ACL of the ACL source (for example,ou=Advertising,o=IBM,c=US, not the ACL of the selected entry (forexample cn=John Doe).

- Do NOT inherit from ACL source - to explicitly define an ACL for theselected entry.

– Allow descendant entries to inherit from this entry - Select the check box toallow descendants without an explicitly defined ACL to inherit from thisentry. If the check box is not selected, descendant entries without an explicitlydefined ACL inherits ACLs from a parent of this entry that has this optionenabled.

– Remove ACL and inherit from ACL source - Select this check box to removethe explicitly defined ACL for this entry and inherit from the ACL source.

v The Subject section displays:– The Distinguished Name (DN) of the entity requesting access to perform

operations on the selected entry. This can also be a pseudo DN.You can:- Select a DN from the drop-down list.- Add a new DN to the list.

1. Replace the entry displayed in the DN field. For example, highlight thetext, click the space bar to erase it, then type the DN you want to add,for example, cn=Marketing Group. Do not delete the entry from thedrop-down list using Delete.

2. Select the Type of entry for the DN. For example, select access-id if theDN is a user.

3. Click Add to add the specified DN to the drop-down list.- Delete a DN from the list.

1. Select the DN from the drop-down list.2. Click Delete.

- Click List all to display all subjects and their rights and permissions in atabular format.


– The Rights section displays the addition and deletion rights of the subject.- Add child grants or denies the subject the right to add a directory entry

beneath the selected entry.- Delete entry grants or denies the subject the right to delete the selected

entry. In the previous example , it grants or denies cn=Marketing Groupthe ability to delete cn=John Doe.

– The Security class section defines permissions for security classes. Attributesare grouped into security classes:- Normal - Normal attribute classes require the least security, for example,

the attribute commonName.- Sensitive - Sensitive attribute classes require a moderate amount of

security, for example homePhone.- Critical - Critical attribute classes require the most security, for example,

the attribute userpassword.

Each security class has permissions associated with it.- Read - the subject can read attributes.- Write - the subject can modify the attributes.- Search - the subject can search attributes.- Compare - the subject can compare attributes.

Additionally, you may specify permissions based on the attribute instead ofthe security class to which the attribute belongs.1. Select an attribute from the Define an attribute drop-down list.2. Click Define.3. Defined attributes are listed below the Critical security class. To remove

an attribute, simply select Unspecified for all permissions, then click OK.

The Owners tab contains two sections:v The DN entry section displays:

– The Owner source is the source of the current Owner for the selected entry.– Select either:

- Remove this list from the entry and use propagated values - to inheritOwner

- Descendant directory tree entries inherit from the entry - to define anOwner for the entry and apply this owner to all descendants that do nothave an explicitly set Owner.

v The Subject section displays:– The Distinguished name (DN) of the Owner of the entry. Owners have

complete access to all attributes for the entry. If the entry does not have anOwner, it inherits an Owner from parent objects based on the Owner settingsof the parent objects. You can:- Select a DN from the drop-down list.- Add a new DN to the drop-down list:

1. Replace the entry displayed in the DN field. For example, highlight thetext, click the space bar to erase it, then type the DN you want to add,for example, cn=Marketing Group. Do not delete the entry from thedrop-down list using Delete.

2. Select the Type of entry for the DN. For example, select access-id if theDN is a user.

3. Click Add to add the specified DN to the drop-down list.


– Delete a DN from the drop-down list:1. Select the DN from the drop-down list.2. Click Delete.


Chapter 8. Secure Sockets Layer

The IBM SecureWay Directory server has the ability to protect LDAP access byencrypting data with Secure Sockets Layer security. When using SSL to secureLDAP communications with the IBM SecureWay Directory, both serverauthentication and client authentication are supported.

With server authentication, the IBM SecureWay Directory server must have adigital certificate (based on the X.509 standard). This digital certificate is used toauthenticate the IBM SecureWay Directory server to the client application (such asNetscape Navigator for HTTP access) or an application built from the applicationdevelopment package, for LDAP access over SSL.

For server authentication The IBM SecureWay Directory server supplies the clientwith the IBM SecureWay Directory server’s X.509 certificate during the initial SSLhandshake. If the client validates the server’s certificate, then a secure, encryptedcommunication channel is established between the IBM SecureWay Directoryserver and the client application.

For server authentication to work, the IBM SecureWay Directory server must havea private key and associated server certificate in the server’s key database file.

To conduct commercial business on the Internet, you might use a widely knownCertification Authority (CA), such as VeriSign, to get a ’high assurance’ servercertificate.

Securing your Server with SSLThe following high-level steps are required to enable SSL support for IBMSecureWay Directory for server authentication. These steps assume you havealready installed and configured the IBM SecureWay Directory server:1. Install the IBM SecureWay Directory GSKit package if it is not installed.2. Generate the IBM SecureWay Directory server private key and server certificate

using the gsk5ikm utility (installed with GSKit). The server’s certificate may besigned by a commercial Certification Authority (CA), such as Verisign, or itmay be self-signed with the gsk5ikm tool. The CA’s public certificate (or theself-signed certificate) must also be distributed to the client application’s keydatabase file.

3. Store the server’s key database file and associated password stash file on theserver. The .../ldap/etc directory is a typical location.

4. Configure the directory to use SSL. See “Configuring the directory to use SSL”on page 94 for additional information.

5. Stop the LDAP server if it is running.6. Restart the LDAP server.

If you also want to have secure communications between a master IBM SecureWayDirectory server and one or more replica servers, you must complete the followingadditional steps:1. Configure the replica directory server.


Note: Follow the steps shown above for the master, except perform them foreach replica. When configuring a replica for SSL, the replica is like themaster with respect to its role when using SSL. The master is an LDAPclient (using SSL) when communicating with a replica.

2. Configure the master directory servera. Add the replica’s signed server certificate to the master directory server’s

key database file, as a trusted root. In this situation, the master directory isactually an LDAP client. If using self-signed certificates, you must extract allthe self-signed certificates from each replica IBM SecureWay Directoryserver, and add them to the master’s key database, and ensure they aremarked as trusted-roots. Essentially, you are configuring the master as anSSL client of the replica server.

b. Configure the master IBM SecureWay Directory server to be aware of thereplica server. Be sure to set the replicaPort attribute to use the port whichthe replica IBM SecureWay Directory server uses for SSL communication.

3. Restart both the master server and each replica server.

Note: Only one key database is permitted per ldap server.

Configuring the directory to use SSL

Note: SSL support is available only if you have IBM’s GSKit installed on yoursystem.

You must add information to the server configuration file, slapd32.conf, to useSSL. Insert the following lines at the end of the slapd32.conf file leaving a blankline to separate them from any other configuration entries.dn: cn=SSL,cn=Configurationcn=SSLibm-slapdSecurePort: 636ibm-slapdSecurity: SSLibm-slapd SSLAuth: serverauthibm-slapdSSLCipherspecs: 12288ibm-slapdSSLKeyDatabase: <filename> (the default is /usr/ldap/etc/ssl.kdb)ibm-slapdSSLKeyDatabasePW: <password>objectclass: topobjectclass: ibm-slapdSSL

The objectclass, dn, and cn values must be as listed, but the other attribute valuescan be set by the server administrator.

ibm-slapdSecurePortThe port number can be set to any unused port. It must not be set to thesame value as ibm-slapdPort.

ibm-slapdSecurityCan be set to:

none The server accepts connections from non-SSL ports only. (The otherparameters are ignored in this case.)

SSL The server accepts connections from both SSL and non-SSL ports.

SSLOnlyThe server accepts connections from SSL ports only.

ibm-slapd SSLAuthCan be set to:


serverauthSupports server authentication at the client. This is the default.

serverclientauthSupports both server and client authentication. It restricts SSLcommunications to clients that have certificates stored in theserver’s key database. This setting must be used for EXTERNALmechanism SASL binds.

ibm-slapdSSLCipherspecsSets the bit mask to the ciphers that are supported by the server. Thedefault value is 12288 for RC2 encryption with a 40-bit key and a MD5MAC (SLAPD_SSL_RC2_MD5_EXPORT) and RC4 encryption with a 40-bitkey and a MD5 MAC (SLAPD_SSL_RC4_MD5_EXPORT). Other supportedvalues are:

512 DES encryption with a 56-bit key and a SHA-1 MAC(SLAPD_SSL_DES_SHA_US)

1024 RC4 encryption with a 128-bit key and a SHA-1 MAC(SLAPD_SSL_RC4_SHA_US)

2048 RC4 encryption with a 128-bit key and a MD5 MAC(SLAPD_SSL_RC4_MD5_US)

4096 RC2 encryption with a 40-bit key and a MD5 MAC(SLAPD_SSL_RC2_MD5_EXPORT)

8192 RC4 encryption with a 40-bit key and a MD5 MAC(SLAPD_SSL_RC4_MD5_EXPORT)

See “Configuring Server Encryption Ciphers” on page 98 and“ibm-slapdSslCipherSpecs” on page 141 for more information onencryption ciphers.

ibm-slapdSSLKeyDatabaseNames the file containing the server’s private certificate. Use the full pathname, for example:ibm-slapdSSLKeyDatabase: /usr/ldap/etc/ssl.kdb

This file is created by the GSKit package’s key manager application,gsk5ikm. When the file is created you have the option of creating a stashfile for the key database file password. If this file is in the same directoryas the key database file, the ibm-slapdSSLKeyDatabasePW is not needed.If you choose not to create a stash file for the password, the passwordmust be supplied as the value for the ibm-slapdSSLKeyDatabasePWattribute.

ibm-slapdSSLKeyDatabasePWSpecifies the password to the key database file if a stash file is not used.Because this password is in clear text, you must limit the file permissionsto the slapd32.conf file to the file owner only.

See “Attributes” on page 125 for more information on these attributes.

Server Certificate from an External Certificate Authority(CA)In order to provide a secure connection between IBM SecureWay Directory and itsclients (Web browsers and LDAP applications), the server must have an X.509certificate and a private key.

Chapter 8. Secure Sockets Layer 95

The steps required to generate a private key, obtain the required server certificatefrom an external certificate authority(CA), and prepare them for use by the IBMSecureWay Directory are outlined in the following:1. Logon using your IBM SecureWay Directory identity.2. Change to the directory where you wish to create the key database file and

where your private key and certificate will be stored.3. Run gsk5ikm to create a new key database file. You may use any valid value

for the key database file name that you want. Whatever file name you use, youwill need to provide it later when configuring the LDAP server to use SSL.Providing a full path name is recommended. The gsk5ikm utility will be usedto generate a private-public key pair and a certificate request.

4. If VeriSign is your external CA, obtain a certificate from the VeriSign Web site,http://digitalid.verisign.com/

5. If you have another CA that you want to use, you follow the directions for thatCA to submit the contents of the certificate request file to them.

When you receive the resulting certificate from the certificate authority(CA):1. Logon using your server identity.2. Change to the directory where you created the key database file.3. Place the signed certificate from the CA into a file in this directory. The file will

be used in the next step.4. From the same directory, run gsk5ikm to receive the certificate into your key

database file.5. Access the LDAP server’s web administrative interface, and configure the

various SSL parameters (including the file specification for the key databasefile).

6. If you have more than one certificate in the key database file, the certificate youwish to use for IBM SecureWay Directory must be the default.

7. Start the IBM SecureWay Directory.

Note: If you instruct gsk5ikm to save the password in a password stash file, it isnot necessary to change or set the password in the slapd32.conf file.

Using a Self-Signed Server CertificateIf you are using the IBM SecureWay Directory in an intranet environment, usegsk5ikm to create your own server certificates. You can also use gsk5ikm to testIBM SecureWay Directory with SSL without purchasing a VeriSign high-assuranceserver certificate. These types of certificates are known as self-signed certificates.

Follow these steps to create a key database file using self-signed certificates.1. On each server:

a. Change to the directory where you wish to create the key database file andwhere your private key and certificate is to be stored.

b. Create a new key database file and the self-sign certificate request that is tobe used as your CA certificate.v Use the largest key size available.v Use a secure server certificate, not a low-assurance certificate.

c. Obtain the certificate request file and the certificate is put into the keydatabase file automatically by the gsk5ikm tool.


http://digitalid.verisign.com/

2. If you are using an application created for the client, do the following on eachclient machine:a. Place the CA certificate request file in an accessible location on the client

machine.b. Receive the CA certificate request file into the client’s key database.c. Mark the received certificate as a trusted root.

3. Most Web browsers allow you to accept or reject the trusted root of anycertificate presented when you attempt to connect to the directory serverthrough an SSL port.

Notes:

1. You must always receive the CA certificate into the server’s key database fileand mark it as a trusted root before receiving the server certificate into theserver’s key database file.

2. Whenever you use gsk5ikm to manage the IBM SecureWay Directory server’skey database file, remember to change to the directory in which the keydatabase file exists.

3. Each IBM SecureWay Directory server should have its own private key andcertificate. Sharing the private key and certificate across multiple IBMSecureWay Directory servers increases security risks. By using differentcertificates and private keys for each server, security exposure is minimized if akey database file for one of the servers is compromised.

4. After changing the key database password using gsk5ikm, run thesetKeyConfig utility with the -p option. If you do not provide parameters theutility also updates the key database file name.

Setting up Your LDAP Client to Access IBM SecureWay DirectoryThe following steps are required to create a key database file for an LDAP clientthat contains one or more self-signed server certificates that are marked as ’trusted’by the client. The process can also be used to import CA certificates from othersources (such as VeriSign) into the client’s key database file for use as trusted roots.A trusted root is simply an X.509 certificate signed by a trusted entity (VeriSign, forexample, or the creator of a self-signed server certificate), imported into the client’skey database file, and ’marked’ as trusted.1. Copy the server’s certificate request file (cert.arm) to your client workstation2. Run gsk5ikm to create a new client key database file or to access an existing

one. For a new client key database, choose a file name associated with theclient for ease of management. For example, if the LDAP client runs on Fred’smachine, you might choose to name the file FRED.KDB

3. If adding server’s certificate to the existing client key database:a. Click Key Database File menu bar and select Open.b. Enter the path and name of the existing key database file then click OK.c. Enter the password.d. Ensure Signer Certificates is chosen and Click on Add.e. Enter the name and location of the server’s certificate filef. Enter a label for the server certificate entry in the client’s key database file,

for example, ’Corporate Directory Server’ then click OK.4. If creating the new Client key database:

a. Click Key DataBase File of menu bar and select New.


b. Enter the name and location for the new Client Key DataBase file, then clickOK.

c. Enter the passwordd. After the new client key database is created, repeat the previous steps for

adding server’s certificate to the existing key database file.5. Exit gsk5ikm.

When the LDAP client creates a secure SSL connection with the server, it now usesthe server’s self-signed certificate to verify that it is connecting to the properserver.

Repeat the preceding steps for each IBM SecureWay Directory server that theLDAP client needs to connect to in a secure fashion.

Configuring Server Encryption CiphersThe following is a list of the ciphers supported:

Non-export VersionsBy default the non-export version of IBM SecureWay Directory server usesthe following list of ciphers when performing cipher negotiation with theclient (during the SSL handshake):v Triple DES encryption with a 168-bit key and an SHA-1 MACv DES encryption with a 56-bit key and an SHA-1 MACv RC4 encryption with a 128-bit key and an SHA-1 MACv RC4 encryption with a 128-bit key and an MD5 MACv RC2 encryption with a 40-bit key and an MD5 MACv RC4 encryption with a 40-bit key and an MD5 MAC

Export VersionsBy default the export version of IBM SecureWay Directory uses thefollowing list of ciphers when performing cipher negotiation with theclient (during the SSL handshake):v DES encryption with a 56-bit key and a SHA-1 MACv RC2 encryption with a 40-bit key and an MD5 MACv RC4 encryption with a 40-bit key and an MD5 MAC

These ciphers are stored in the configuration file using the sslCipherSpecskeyword as the decimal representation of the or’d bitmask defined by the valuesabove. For example, to use only Triple DES, the value is 256. In this case, onlyclients that also support Triple DES would be able to establish an SSL connectionwith the server.

Client AuthenticationClient authentication provides for two-way authentication between the LDAPclient and the LDAP server.

With client authentication, the LDAP client must have a digital certificate (based onthe X.509 standard). This digital certificate is used to authenticate the LDAP clientto the IBM SecureWay Directory Server.

The Simple Authentication and Security Layer (SASL) can be used to addauthentication support to connection protocols. A protocol includes a command for


identifying and authenticating a user to a server. It can optionally negotiate asecurity layer for subsequent protocol interactions.

After a server receives the authentication command or any client response, it mayissue a challenge or indicate failure or completion. If a client receives a challenge itmay issue a response or abort the exchange, depending on the profile of theprotocol.

During the authentication protocol exchange, the SASL mechanism performsauthentication, transmits an authorization identity (known as userid) from theclient to the server, and negotiates the use of a mechanism-specific security layer.

When the LDAP server receives an LDAP bind request from a client, it processesthe request in the following order:1. The server parses the LDAP bind request and retrieves the following

information:v The DN that the client is attempting to authenticate as.v The method of authentication used.v Any credentials, such as a password included in the request.v If the method of authentication is SASL, the server also retrieves the name of

the SASL mechanism used from the LDAP bind request.2. The server normalizes the DN retrieved from the request.3. The server retrieves any LDAP control included with the LDAP bind request.4. If the method of authentication is SASL, the server determines whether or not

the SASL mechanism (specified in the request) is supported. If the SASLmechanism is not supported by the server, the server sends an error returncode to the client and ends the bind process.

5. If the SASL mechanism is supported (=EXTERNAL) and the SSL authenticationtype is server and client authentication, the server verifies that the client’scertificate is valid, issued by a known CA, and that none of the certificates onthe client’s certificate chain are invalid or revoked. If the client DN andpassword, as specified in the ldap_sasl_bind, are NULL, then the DNcontained within the client’s x.509v3 certificate is used as the authenticatedidentity on subsequent LDAP operations. Otherwise, the client is authenticatedanonymously (if DN and password are NULL), or the client is authenticatedbased on the bind information provided by the client.

6. If the method of authentication is Simple, the server checks to see if the DN isan empty string or if there are no credentials.

7. If the DN is an empty string, or if the DN or no credentials are specified, theserver assumes that the client is binding anonymously and returns a goodresult to the client. The DN and authentication method for the connection areleft as NULL and LDAP_AUTH_NONE respectively.

8. If the client has not bound beforehand, and does not present a certificateduring the bind operation, the client is authenticated anonymously.

When using SSL to secure LDAP communication with the IBM SecureWayDirectory server with client authentication mechanism, you can manually edit theslapd32.conf file under the cn=SSL, cn=Configuration entry to add the new line:ibm-slapdSSLAuth: serverclientauth

For server authentication, you can either omit sslAuth attribute or set it as follows:ibm-slapdSSLAuth: serverauth


Chapter 9. Working with attributes

Each directory entry has a set of attributes associated with it through it’s objectclass. You can create, edit, or delete attributes to suit the needs of yourorganization.

Adding an attributeIf you have not done so already, expand the Schema category in the navigationarea, then expand Attributes.1. Click Add attribute.2. Select a tab, either:

v General to:– Enter the Attribute name, for example, tempId. This is the only required

field and must begin with an alphabetical character.– Enter a Description of the attribute, for example, The ID number

assigned to a temporary employee.– Enter the OID for the attribute. The OID defaults to the Attribute name

appended with -OID. For example, if the attribute name is tempID, thenthe default OID is tempID-OID. You can change the value of this field.

– Select a Superior attribute from the drop-down list. The Superior attributedetermines the attribute from which properties are inherited.

– Select a Syntax from the drop-down list. See the glossary entry foradditional information about Syntax.

– Enter a Syntax length.

Note: Syntax length is not a mandatory field. It defaults to 240 bytes for astring and 256 bytes for a binary. A string can range from aminimum of 1byte to a maximum of 32700 bytes. The maximum fora binary is 2 GB.

– Select the Allow multiple values checkbox to enable the attribute to havemultiple values. See the glossary entry for additional information aboutmultiple values.

– Select a Matching rule from the drop-down list. See the glossary entry foradditional information about matching rules.

v IBM Extensions, if you are using the IBM SecureWay Directory Server, to:– Modify the DB2 table name . The server generates the DB2 table name if

this field is left blank. If you enter a DB2 table name, you must also entera DB2 column name.

– Modify the DB2 column name. The server generates the DB2 coulmnname if this field is left blank. If you enter a DB2 column name, you mustalso enter a DB2 table name.

– Set the Security class by selecting normal, sensitive, or critical from thedrop-down list.

– Set the Indexing rules. See “Appendix A. Indexing rules” on page 115 foradditional information about indexing rules.

Note: Default values made by the server for fields with no value specifiedare not visible until you refresh the schema or rebind to the server.


3. Click OK to add the new attribute or click Cancel to return to View attributeswithout making any changes.

Editing an attributeIf you have not done so already, expand the Schema category in the navigationarea, then expand Attributes.1. Click Edit attribute.2. Select an attribute to edit using the Attribute drop-down list.3. Select a tab, either:

v General to:– Modify the Description

– Change the Syntax

– Set the Syntax length

Note: Syntax length is not a mandatory field. It defaults to 240 bytes for astring and 256 bytes for a binary. A string can range from aminimum of 1byte to a maximum of 32700 bytes. The maximum fora binary is 2 GB.

– Change the Multiple value settings– Select a Matching rule

– Change the Superior attribute

v IBM Extensions, if you are using the IBM SecureWay Directory Server, to:– Change the Security class

– Change the Indexing rules

4. Click OK to add the new attribute or click Cancel to return to View attributeswithout making any changes.

See “Adding an attribute” on page 101 help for additional information aboutattributes.

Deleting an attributeIf you have not done so already, expand the Schema category in the navigationarea, then expand Attributes.1. Click Delete attributes.2. Select an attribute to delete. Select multiple attributes using the Ctrl key.3. Click Delete to remove the selected attribute. You are prompted to confirm

deletion of the attribute. If deleting multiple attributes, you can click Yes to allto confirm deletion of all selected attributes.

Binary attributes

Binary attributes, such as images, are indicated by to the left of the attributefield.

Because binary attributes cannot be displayed, if an attribute contains binary data,the field displays **** BINARY DATA ****. If the attribute contains multiplevalues, the field displays as a drop-down list. Click the icon to work with binaryattributes.


If the attribute has no data, a browse window is displayed. Select the file thatcontains the binary data and click Import.

If the attribute already contains data, you are prompted to either Update theexisting data or Export the existing data to a file.v To update existing data:

1. Click OK. You are prompted to either Add new data, Replace all existingdata, or Delete all existing data.– To add new data, select Add, then click OK. A browse window is

displayed. Select the file that contains the binary data and click Import.– To replace all data, select Replace all, then click OK. A browse window is

displayed. Select the file that contains the binary data and click Import.Replacing all data deletes all existing data and adds the one specified file.

– To delete all entries, select Delete all, then click OK.v To export existing data to a file:

1. Select Export.2. Click OK. A browse window displays.3. Select the location of the file and enter the file name, then click Export.

Chapter 9. Working with attributes 103

Chapter 10. Working with object classes

An object class is a set of attributes used to describe an object. For example, theobject class tempEmployee could contain attributes associated with a temporaryemployee such as, idNumber, dateOfHire, or assignmentLength. You can addcustom object classes to suit the needs of your organization.

Adding an object classIf you have not done so already, expand the Schema category in the navigationarea, then expand Object classes.1. Click Add object class.2. Select a tab:

v Use General to set the basic properties for the object class.– Enter the Object class name. This is the only required field, and is

descriptive of the function of the object class. For example, tempEmployeefor an object class used to track temporary employees.

– Enter a Description of the object class, for example, The object class usedfor temporary employees.

– Enter the OID for the object class. The OID defaults to the Object classname appended with -OID. For example, if the object class name istempEmployee, then the default OID is tempEmployee-OID. You canchange the value of this field.

– Select a Superior object class from the drop-down list. The Superiorobject class defaults to top and determines the object class from whichother attributes are inherited. For example, a superior object class fortempEmployee might be ePerson.

– Select an Object class type. See the glossary entry for additionalinformation about object class types.

v Use Required attributes to select required attributes and view the inheritedrequired attributes.– Select an attribute from the alphabetical list of Available attributes and

click Add to make the attribute required for the object class. Add multipleattributes using the Ctrl key.

– Inherited attributes are based on the Superior object class selected on theGeneral tab. You can not change the inherited attributes without changingthe Superior object class on the General tab.

3. Click OK to add the new object class or click Cancel to return to View objectclasses without making any changes.

Editing an object classIf you have not done so already, expand the Schema category in the navigationarea, then expand Object classes.1. Click Edit object class.2. Select an object class to edit using the Object class name drop-down list.3. Select a tab:

v Use General to:


– Modify the Description.– Change the Object class type. See the glossary entry for additional

information about object class types.v Use Required attributes to:

– Add required attributes for the object class. Select an attribute from thealphabetical list of Available attributes and click Add to make theattribute required for the object class. Add multiple attributes using theCtrl key.

– Remove required attributes from the object class. Select an attribute fromthe alphabetical list of Required attributes and click Remove to notrequire the attribute for the object class. Remove multiple attributes usingthe Ctrl key.

Note: Inherited attributes are based on the Superior object class selected onthe General tab. You can not change the inherited attributes withoutchanging the Superior object class on the General tab.

v Use Optional attributes to:– Add optional attributes for the object class. Select an attribute from the

alphabetical list of Available attributes and click Add to make theattribute optional for the object class. Add multiple attributes using theCtrl key.

– Remove optional attributes from the object class. Select an attribute fromthe alphabetical list of Optional attributes and click Remove to removethe optional attribute from the object class. Remove multiple attributesusing the Ctrl key.

Note: Inherited attributes are based on the Superior object class selected onthe General tab. You can not change the inherited attributes withoutchanging the Superior object class on the General tab.

4. Click OK to add the new object class or click Cancel to return to View objectclasses without making any changes.

Deleting an attributeIf you have not done so already, expand the Schema category in the navigationarea, then expand Attributes.1. Click Delete object classes.2. Select an object class to delete. Select multiple object classes using the Ctrl key.3. Click Delete to remove the selected object class. You are prompted to confirm

deletion of the object class. If deleting multiple object classes, you can click Yesto all to confirm deletion of all selected object classes.


Chapter 11. Viewing the log file

View the log file to review error messages, directory and schema modifications,and server connection information for the current server. Servers are displayed astabs in the navigation area. The current server is the selected tab in the navigationarea.1. If you have not done so already, expand the Log file category in the navigation

area.2. Click View log file. The log file for the current server is displayed in the work

area. The log displays the most recent log entry at the bottom of the panel.3. To clear the log file, Click Clear log file in the navigation area. Clearing the log

file removes all log entries for the current server, leaving only a log messagestating that the log was cleared.


Chapter 12. Working with directory entries

You can perform the following operations with directory entries:v Search for entriesv Add an entryv Add an auxiliary object class to an entryv Edit an entry

Searching the directory tree for entriesThere are two options for searching the directory tree:v A Simple search using a predefined set of search criteriav An Advanced search using a user-defined set of search criteria

Both search options are accessible by expanding the Directory tree category in thenavigation area, then expanding Search tree.

Simple searchA simple search uses a default search criteria:v Base DN is All suffixes

v Search scope is Subtree

v Search size is Unlimited

v Time limit is Unlimited

v Alias dereferencing is never

v Chase referrals is deselected (off)

To perform a simple search:1. If you have not done so already, expand the Directory tree category, then

expand Search tree.2. Click Simple search.3. Select an entry type from the commonly used object classes or select Other if

the entry type is not listed. If you select Other, select an object class from thedrop-down list.

4. Select to either Show all directory entries of the selected entry type or select toSearch on a specific attribute for the selected entry type. If you select to searchon a specific attribute, select an attribute from the drop-down list and enter theattribute value in the Search for box.

5. Click OK to begin the search based on the criteria specified or click Cancel toreturn to Browse tree without performing the search.

Advanced searchAn advanced search enables you to specify search constraints and enable searchfilters. Use the Simple search to use default search criteria.v Search filter tab

1. Select an Attribute from the drop-down list.2. Select a Comparison operator

– =The attribute is equal to the value.


– ! The attribute is not equal to the value.– < The attribute is less than or equal to the value.– > The attribute is greater than or equal to the value.– ˜ The attribute approximately equal to the value.

3. Enter the Value for comparison.4. Use the search operator buttons for complex queries.

– Click Add to add the search filter criteria to the advanced search– If you already added at least one search filter, specify the additional

criteria and click AND. The AND command returns entries that matchboth sets of search criteria.

– If you already added at least one search filter, specify the additionalcriteria and click OR. The OR command returns entries that match eitherset of search criteria.

– Click Reset to clear all search filters.v Search constraints tab

– Search base DN - Select All suffixes to search within all suffixes, or select ortype a suffix from the drop-down list to search only within that suffix.

– Search scope

- Select Object to search only within the selected object.- Select Single level to search only within the immediate children of the

selected object.- Select Subtree to search all descendants of the selected entry.

– Search size limit - Enter the maximum number of entries to search or selectUnlimited.

– Search time limit - Enter the maximum number of seconds for the search orselect Unlimited.

– Select a type of Alias dereferencing from the drop-down list.- never - If the selected entry is an alias, it is not dereferenced for the search,

that is, the search ignores the reference to the alias.- finding - If the selected entry is an alias, the search dereferences the alias

and search from the location of the alias.- searching - The selected entry is not dereferenced, but any entries found in

the search are dereferenced.- always - All aliases encountered in the search are dereferenced.

– Select the Chase referrals check box to follow referrals to another server if areferral is returned in the search. When a referral directs the search to anotherserver, the connection to the server uses the current credentials. If you arelogged in as Anonymous you might need to rebind to the server using anauthenticated DN. See “Connecting to a server” on page 75 for information onrebinding. See “Working with referrals” on page 44 for more informationabout referrals.

v Click OK to begin the advanced search or click Cancel to return to Browse treewithout performing the search.

After performing a search, click Save search to save the search criteria. Savedsearches are displayed under the Search tree category in the navigation area.Clicking a saved search in the navigation area start the search and display thesearch results.


Editing a saved searchTo edit a saved search:1. Under the Search tree category in the navigation area, click Edit search in the

navigation area.2. Select a saved search to edit, then click OK.3. Edit the search criteria and click OK to start the search and verify the expected

results.4. Click Save search.5. You are prompted to specify the search name. The default is the previously

saved name, however, you can modify the search name.

Deleting a saved searchTo delete a saved search:1. Under the Search tree category in the navigation area, click Delete search in

the navigation area.2. Select a saved search to delete, then click Delete.3. You are prompted to confirm the deletion of each selected saved search. Click

Yes to all to confirm deletion of all selected searches and bypass theconfirmation for each selected search.

Adding an LDAP entryIf you have not done so already, expand the Directory tree category in thenavigation area.1. Click Add on the toolbar.2. Select an Entry type, or select Other to select an entry type that is not listed. If

you select Other as the Entry type :v Select one Structural object class from the drop-down list .v Select any Auxiliary object classes you wish to use from the list box. Select

multiple auxiliary object classes using the Ctrl key.

The Current definition tab shows the object classes, required attributes, andoptional attributes based on the selections on the Object class tab.

3. In the Parent DN field, enter the distinguished name of the tree entry youselected, for example, ou=Austin, o=IBM. The Parent DN defaults to the entryselected in the tree.

4. In the Entry RDN field, enter the relative distinguished name (RDN) of theentry that you are adding, for example, cn=John Doe.

5. Click OK to continue or click Cancel to return to Browse tree without makingany changes to the directory.

6. Enter the DN for the new entry. The default DN is the Parent DN plus theEntry RDN from the Add an LDAP Entry panel.Depending on the Entry type you selected a series of tabs is displayed on thispanel. Most entry types display an Attributes tab. The User entry displaysthree tabs: Business, Personal, and User. The Group entry displays two tabs:Group and Other.v Required fields are indicated by a bold or boxed field label and are listed at

the top of each tab.

Chapter 12. Working with directory entries 111

v The pencil icon indicates the attribute can have multiple values, forexample, to accommodate a maiden and married last name. To add multiplevalues to an attribute, click the pencil icon, then add one value per line.

v The binary attribute icon indicates the syntax for the attribute is binary,for example, an image. See “Binary attributes” on page 102 for additionalinformation.

You can move the mouse over the field name or field to display the attributesyntax, for example, IA5 String - case-sensitive string.

7. Click the ACL button to modify the access control list for this entry. See“Working with Access Control Lists” on page 89 for information on ACLs.

8. After completing at least the required fields, click Add to add the new entry orclick Cancel to return to Browse tree without making changes to the directory.

Adding an auxiliary object classUse the Add auxiliary class button on the toolbar to add an auxiliary object classto an existing entry in the directory tree. An auxiliary object class providesadditional attributes to the entry to which it is added.

If you have not done so already, expand the Directory tree category in thenavigation area.1. Click Browse tree.2. Select an entry and click Add auxiliary class on the toolbar.3. Select an Auxiliary class. Select multiple auxiliary classes using the Ctrl key.4. Click OK to add the auxiliary class to the entry and edit the entry, or click

Cancel to return to Browse tree without making any changes.

Editing an LDAP entryIf you have not done so already, expand the Directory tree category in thenavigation area.1. Select a directory entry and click Edit on the toolbar.

The Edit entry panel contains tabs for the attributes associated with the objectclass. The Summary tab displays the completed attributes for that entry. Usersand Groups have tabs specific to the User and Group entry types as follows:The Users entry contains five tabs:v The Business tab contains attributes related to the business of the user.v The Personal tab contains attributes related to the personal information

about the user.v The Other tab contains additional attributes for the user.v The Summary tab contains a summary of the completed fields from the

Business, Personal, and Other tabs. The Summary tab does not displaywhen adding a User, only when editing a User.

v The Memberships tab displays the groups of which the user is currently amember. The Memberships tab does not display when adding a User, onlywhen editing a User. For additional information, see “Changing groupmembership” on page 114.

The Groups entry contains three tabs:


v The General tab contains required attributes for groups and a descriptionfield.

v The Other tab contains additional attributes for the group.v The Summary tab contains a summary of the completed fields from the

General and Other tabs. The Summary tab does not display when adding aGroup, only when editing a Group.

v Required fields are indicated by a bold or boxed field label and are listed atthe top of each tab.

v The pencil icon indicates the attribute can have multiple values, forexample, to accommodate a maiden and married last name. To add multiplevalues to an attribute, click the pencil icon, then add one value per line. If anattribute contains multiple values, the field displays as a drop-down list.

Note: You can add an additional common name using the multi-valuedoption, however, you can not remove or modify the original commonname assigned to the entry.

v The binary attribute icon indicates the syntax for the attribute is binary,for example, an image. If a binary attribute contains multiple values, the fielddisplays as a drop-down list. See “Binary attributes” on page 102 foradditional information.

You can move the mouse over the field name or field to display the attributesyntax, for example, IA5 String - case-sensitive string.

2. Click the ACL button to modify the access control list for this entry. See“Working with Access Control Lists” on page 89 for information on ACLs.

3. Edit the attributes, then click OK to save your changes or click Cancel to returnto Browse tree without making changes.

Groups and RolesAlthough group-base authorization and role-based authorization are similar, thereare some differences.

GroupsThere are two type of groups:v Normal groups, which have an object class of ’GroupOfNames’,

’GroupOfUniqueNames’ or a user defined group.v Groups used for access control, which have an object class of ’AccessGroup’.

Each group object contains a multivalued attribute consisting of member DNs.Groups cannot contain group DNs.

Groups can have members added or deleted. If a user entry is deleted from adirectory, it is removed from all groups to which it belongs. No local versusforeign DN checking is performed. Any DN can be added to a group.

Upon deletion of an access group, the access group is also deleted from all ACLsto which it has been applied.

RolesRole-based authorization is a conceptual complement to the group-basedauthorization, and is useful in some cases. As a member of a role, you have the

Chapter 12. Working with directory entries 113

authority to do what is needed for the role in order to accomplish a job. Unlike agroup, a role comes with an implicit set of permissions. There is not a built-inassumption about what permissions are gained (or lost) by being a member of agroup.

Roles are similar to groups in that they are represented in the directory by anobject. Additionally, roles contain a group of dns. Roles which are to be used inaccess control must have an objectclass of ’AccessRole’. The ’Accessrole’ objectclassis a subclass of the ’GroupOfNames’ objectclass.

For example, if there are a collection of DNs such as ’sys admin’, your firstreaction might be to think of them as the ’sys admin group’ (because groups andusers are the most familiar types of privilege attributes). However, because there isa set of permissions that you expect to receive as a member of ’sys admin’ thecollection of DNs might be more accurately defined as the ’sys admin role’.

Changing group membershipIf you have not done so already, expand the Directory tree category in thenavigation area.1. Click Browse tree.2. Select a user from the directory tree and click the Edit icon on the toolbar. User

entries have an icon to the left of their entry in the directory tree.3. Click the Memberships tab.4. Click Change to modify the memberships for the user. The Change

memberships panel displays the Available groups to which the user can beadded, as well as the entries Member of groups.v Select a group from Available groups and click Add to make the user a

member of the selected group.v Select a group from Member of groups and click Remove to remove the user

from the selected group.5. Click OK to save your changes or click Cancel to return to the previous panel

without saving your changes.


Appendix A. Indexing rules

Index rules attached to attributes make it possible to retrieve information faster. Ifonly the attribute is given, all possible indexes are maintained. IBM SecureWayDirectory provides the following indexing rules:v Equalv Approximatev Substring

Indexing Rules Specifications for Attributes:Specifying an indexing rule for an attribute controls the creation and maintenanceof special indexes on the attribute values. This greatly improves the response timeto searches with filters which include those attributes. The three possible types ofindexing rules are related to the operations applied in the search filter.

Equal Applies to the following search operations:v equalityMatch ’=’v greaterOrEqual ’>=’v lessOrEqual ’<=’

For example:"cn = John Doe""sn >= Doe"

ApproximateAapplies to the following search operation:v approxMatch ’x=’

For example:"sn x= doe"

SubstringApplies to the search operation using the substring syntax:v substrings ’*’

For example:"sn = McC*""sn = *baugh""cn = J*Doe"

At a minimum, it is recommended that you specify Equal indexing on anyattributes that are to be used in search filters.


Appendix B. IBM SecureWay Directory Configuration Schema

This appendix describes the Directory Information Tree (DIT) and the Attributesthat are used to configure the slapd32.conf file. In previous releases the directoryconfiguration settings were stored in a proprietary format in the slapd.conf file.With the Version 3.2 release the directory settings are stored using the LDIF formatin the slapd32.conf file.

Directory Information Tree (DIT)cn=Configurationv cn=Event Notificationv cn=Front Endv cn=Kerberosv cn=Master Serverv cn=Referralv cn=Schema

– cn=IBM SecureWay- cn=RDBM Backends

v cn=Directoryv cn=ChangeLog

- cn=LDCF Backendsv cn=SchemaDB

v cn=SSL– cn=CRL

v cn=Transaction

cn=ConfigurationDN cn=Configuration

DescriptionThis is the top-level entry in the configuration DIT. It holds data of globalinterest to the server, although in practice it also contains miscellaneousitems. Every attribute in the this entry comes from the first section (globalstanza) of slapd32.conf.

Number1 (required)

Object Classibm-slapdTop

Mandatory Attributes

v cnv ibm-slapdAdminDNv ibm-slapdAdminPWv ibm-slapdErrorLogv portibm-slapdPortv ibm-slapdPwEncryption


v ibm-slapdSizeLimitv ibm-slapdSysLogLevelv ibm-slapdTimeLimitv objectClass

Optional Attributes

v ibm-slapdConcurrentRW

cn=Event NotificationDN cn=Event Notification, cn=Configuration

DescriptionGlobal event notification settings for IBM SecureWay 3.2.2

Number1 (required)

Object Classibm-slapdEventNotification


v cnv ibm-slapdEnableEventNotificationv objectClass

Optional Attributes

v ibm-slapdMaxEventsPerConnectionv ibm-slapdMaxEventsTotal

cn=Front EndDN cn=Front End, cn=Configuration

DescriptionGlobal environment settings that the server applies at startup.

Number0 or 1 (optional)

Object Classibm-slapdFrontEnd


v cnv objectClass

Optional Attributes

v ibm-slapdPluginv ibm-slapdSetenv

cn=KerberosDN cn=Kerberos, cn=Configuration

DescriptionGlobal kerberos authentication settings for IBM SecureWay 3.2.2



Object Classibm-slapdKerberos


v cnv ibm-slapdKrbEnablev ibm-slapdKrbRealmv ibm-slapdKrbKeyTabv ibm-slapdKrbIdentityMapv ibm-slapdKrbAdminDNv objectClass

Optional Attributes

v None

cn=Master ServerDN cn=Master Server, cn=Configuration

DescriptionWhen configuring a replica, this entry holds the bind credentials andreferral URL of the master server. This is also the section used forPeer-to-Peer replication. ibm-slapdPeerDN and ibm-slapdPeerPW aremutually exclusive with ibm-slapdMasterDN and ibm-slapdMasterPW.Peer-to-Peer must be set manually. See the Peer-to-Peer documentation inthe Server Readme.


Object Classibm-slapdReplication


v cnv ibm-slapdMasterDNv ibm-slapdMasterPW (If using kerberos authentication, this attribute is

optional.)v ibm-slapdMasterReferralv objectClass

Optional Attributes

v ibm-slapdMasterPW (If not using kerberos authentication, this attributeis manditory.)

cn=ReferralDN cn=Referral, cn=Configuration

DescriptionThis entry contains all the ″referral″ entries from the first section (globalstanza) of slapd32.conf. If there are no referrals (there are none by default),this entry is optional.


Appendix B. IBM SecureWay Directory Configuration Schema 119

Object Classibm-slapdReferral


v cnv ibm-slapdReferralv objectClass

Optional Attributes

v None

cn=SchemasDN cn=Schemas, cn=Configuration

DescriptionThis entry serves as a container for the schemas. This entry is not reallynecessary because the schemas can be distinguished by the object classibm-slapdSchema. It is included to help improve the readability of thedirectory information tree (DIT).

Only one schema entry is currently allowed: cn=IBM SecureWay.

Number1 (required)

Object ClassContainer


v cnv objectClass

Optional Attributes

v None

cn=IBM SecureWayDN cn=IBM SecureWay, cn=Schemas, cn=Configuration

DescriptionThis entry contains all the schema configuration data from the first section(global stanza) of slapd32.conf. It also serves as a container for all thebackends which use the schema. Multiple schemas are not currentlysupported, but if they were, then there would be one ibm-slapdSchemaentry per schema. Note that multiple schemas are assumed to beincompatible. Therefore, a backend can only be associated with a singleschema.

Number1 (required)

Object Classibm-slapdSchema


v cnv ibm-slapdSchemaAdditionsv ibm-slapdSchemaCheckv ibm-slapdIncludeSchema


v objectClass

Optional Attributes

v None

cn=RDBM BackendsDN cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration

DescriptionThis entry serves as a container for the Relational Database Management(RDBM) backends. It effectively replaces the ″database rdbm″ line from theVersion 3.1 configuration file, slapd.conf, by identifying all sub-entries asDB2 backends. This entry is not really necessary because the RDBMbackends can be distinguished by object class ibm-slapdRdbmBackend. It isincluded to help improve the readability of the DIT

Number1 (required)



v cnv objectClass

Optional Attributes

v UseProcessIdPw

cn=DirectoryDN cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas,

cn=Configuration

DescriptionThis entry contains all the database configuration settings for the defaultrdbm database backend.

Although multiple backends with arbitrary names can be created, theServer Administration assumes that ″cn=Directory″ is the main directorybackend, and that ″cn=Change Log″ is the optional changelog backend.Only the suffixes displayed in ″cn=Directory″ are configurable through theServer Administration (except for the changelog suffix, which is settransparently by enabling changelog).

Number1 - n

Object Classibm-slapdRdbmBackend


v cnv ibm-slapdDbConnectionsv ibm-slapdDbInstancev ibm-slapdDbNamev ibm-slapdDbUserIDv ibm-slapdPlugin


v objectClass

Optional Attributes

v ibm-slapdChangeLogMaxEntriesv dbusridibm-slapdDbUserPWv roibm-slapdReadOnlyv ibm-slapdSuffixv ibm-slapdUseProcessIdPw

cn=Change LogDN cn=Change Log, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas,

cn=Configuration

DescriptionThis entry contains all the database configuration settings for the changelog backend.

Number0 - n (optional)

Object Classibm-slapdRdbmBackend


v cnv ibm-slapdDbConnectionsv ibm-slapdDbInstancev ibm-slapdDbNamev ibm-slapdDbUserIDv ibm-slapdPluginv objectClass

Optional Attributes

v ibm-slapdChangeLogMaxEntriesv ibm-slapdDbUserPWv ibm-slapdReadOnlyv ibm-slapdSuffixv ibm-slapdUseProcessIdPw

cn=LDCF BackendsDN cn=LDCF Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration

DescriptionThis entry serves as a container for the LDAP Configuration (LDCF)backends. It effectively replaces the ″database ldcf″ line from the Version3.1 configuration file, slapd.conf, by identifying all sub-entries as LDCFbackends. This entry is not really necessary because the LDCF backendscan be distinguished by the object class ibm-slapdLdcfBackend. It isincluded to help improve the readability of the DIT.

Number1 (required)




v cnv objectClass

Optional Attributes

v ibm-slapdPlugin

cn=SchemaDBDN cn=SchemaDB, cn=LDCF Backends, cn=IBM SecureWay, cn=Schemas,

cn=Configuration

DescriptionThis entry contains all the database configuration data from the ldcfdatabase section of slapd32.conf.

Number1 (required)

Object Classibm-slapdLdcfBackend


v cnv objectClass

Optional Attributes

v ibm-slapdPluginv ibm-slapdSuffix

cn=SSLDN cn=SSL, cn=Configuration

DescriptionGlobal SSL connection settings for IBM SecureWay 3.2.2


Object Classibm-slapdSSL


v cnv ibm-slapdSecurityv ibm-slapdSecurePortv ibm-slapdSslAuthv ibm-slapdSslCipherSpecsv ibm-slapdSslKeyDatabasev objectClass

Optional Attributes

v ibm-slapdSslCertificatev ibm-slapdSslKeyDatabasePW


cn=CRLDN cn=CRL, cn=SSL, cn=Configuration

DescriptionThis entry contains certificate revocation list data from the first section(global stanza) of slapd32.conf. It is only needed if ″ibm-slapdSslAuth =serverclientauth″ in the cn=SSL entry and the client certificates have beenissued for CRL validation.


Object Classibm-slapdCRL


v cnv ibm-slapdLdapCrlHostv ibm-slapdLdapCrlPortv objectClass

Optional Attributes

v ibm-slapdLdapCrlUserv ibm-slapdLdapCrlPassword

cn=TransactionDN cn = Transaction, cn = Configuration

DescriptionSpecifies Global transaction support settings. Transaction support isprovided using the plugin:

Windows®:extendedop /bin/libtranext.dll tranExtOpInit 1.3.18.0.2.12.51.3.18.0.2.12.6

AIX:extendedop /lib/libtranext.a tranExtOpInit 1.3.18.0.2.12.51.3.18.0.2.12.6

Solaris:extendedop /lib/libtranext.so tranExtOpInit 1.3.18.0.2.12.51.3.18.0.2.12.6

The server (slapd) loads this plugin automatically at startup ifibm-slapdTransactionEnable = TRUE. The plugin does not need to beexplicitly added to slapd32.conf.

Number1 (required)

Object Classibm-slapdTransaction


v cnv ibm-slapdMaxNumOfTransactions


v ibm-slapdMaxOpPerTransactionv ibm-slapdMaxTimeLimitOfTransactionsv ibm-slapdTransactionEnablev objectClass

Optional Attributes

v None

Attributesv cnv ibm-slapdAdminDNv ibm-slapdAdminPWv ibm-slapdChangeLogMaxEntriesv ibm-slapdConcurrentRWv ibm-slapdDbConnectionsv ibm-slapdDbInstancev ibm-slapdDbLocationv ibm-slapdDbNamev ibm-slapdDbUserIDv ibm-slapdDbUserPWv ibm-slapdEnableEventNotificationv ibm-slapdErrorLogv ibm-slapdIncludeSchemav ibm-slapdKrbAdminDNv ibm-slapdKrbEnablev ibm-slapdKrbIdentityMapv ibm-slapdKrbKeyTabv ibm-slapdKrbRealmv ibm-slapdLdapCrlHostv ibm-slapdLdapCrlPasswordv ibm-slapdLdapCrlPortv ibm-slapdLdapCrlUserv ibm-slapdMasterDNv ibm-slapdMasterPWv ibm-slapdMasterReferralv ibm-slapdMaxEventsPerConnectionv ibm-slapdMaxEventsTotalv ibm-slapdMaxNumOfTransactionsv ibm-slapdMaxOpPerTransactionv ibm-slapdMaxTimeLimitOfTransactionsv ibm-slapdPluginv ibm-slapdPortv ibm-slapdPwEncryptionv ibm-slapdReadOnlyv ibm-slapdReferralv ibm-slapdSchemaAdditions


v ibm-slapdSchemaCheckv ibm-slapdSecurePortv ibm-slapdSecurityv ibm-slapdSetenvv ibm-slapdSizeLimitv ibm-slapdSslAuthv ibm-slapdSslCertificatev ibm-slapdSslCipherSpecsv ibm-slapdSslKeyDatabasev ibm-slapdSslKeyDatabasePWv ibm-slapdSuffixv ibm-slapdSysLogLevelv ibm-slapdTimeLimitv ibm-slapdTransactionEnablev ibm-slapdUseProcessIdPwv objectClass

cnDescription

This is the X.500 common Name attribute, which contains a name of anobject.

SyntaxDirectory string

Maximum Length256

Value Multi-valued

ibm-slapdAdminDNDescription

The administrator bind DN for IBM SecureWay Directory server.

Defaultcn=root

SyntaxDN

Maximum Length512

Value Single-valued

ibm-slapdAdminPWDescription

The administrator bind Password for IBM SecureWay Directory server.

DefaultNo preset default is defined.

SyntaxBinary


Maximum Length128

Value Single-valued

ibm-slapdChangeLogMaxEntriesDescription

This attribute is used by a changelog plugin to specify the maximumnumber of changelog entries allowed in the RDBM database. Eachchangelog has its own changeLogMaxEntries attribute.Minimum = 0 (unlimited)Maximum = 2,147,483,647 (32-bit, signed integer)

Default0

SyntaxInteger

Maximum Length11

Value Single-valued

ibm-slapdConcurrentRWDescription

Setting this to TRUE allows searches to proceed simultaneously withupdates. It allows for ’dirty reads’, that is results that might not beconsistent with the committed state of the database.

DefaultFALSE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdDbConnectionsDescription

Specifies the number of DB2 connections the server dedicates to thisbackend. The minimum is three. The maximum is 7 for AIX, 31 for Solaris,and 37 for NT.

Note: ODBCCONS environment variable overrides the value of thisdirective.

Never use the maximum number of DB2 connections, or there will be noneavailable for other processes like bulkload, ldif2db or ServerAdministration.

The server requires a minimum of three connections per backend. One isreserved for replication and one for modify operations, all remainingconnections are used for searches.


Default6 for AIX, 9 for Windows NT, and 5 for Solaris

SyntaxInteger

Maximum Length2

Value Single-valued

ibm-slapdDbInstanceDescription

Specifies the DB2 database instance for this backend.

Defaultldapdb2

SyntaxDirectory string with case-exact matching

Maximum Length8

Value Single-valued

ibm-slapdLocationDescription

The ibm-slapdDbLocation parameter is read by the ChangeLog creationcode to locate the main database. This value should not be changed by theuser after it is established.


Syntax

On Unix systems, this value is the path where the main database islocated. For example, ibm-slapdDbLocation: /home/ldapdb2

On Windowssystems, the value is a drive letter followed by a colon. Forexample, ibm-slapdDbLocation: C:

Maximum LengthAs per operating system.

Value Single-valued

ibm-slapdDbNameDescription

Specifies the DB2 database name for this backend.

Defaultldapdb2


Maximum Length8

Value Single-valued


ibm-slapdDbUserIDDescription

Specifies the user name with which to bind to the DB2 database for thisbackend.

Defaultldapdb2


Maximum Length8

Value Single-valued

ibm-slapdDbUserPWDescription

Specifies the user password with which to bind to the DB2 database forthis backend. The password can be plain text or imask encrypted.

Defaultldapdb2

SyntaxBinary

Maximum Length128

Value Single-valued

ibm-slapdEnableEventNotificationDescription

Specifies whether to enable Event Notification. It must be set to eitherTRUE or FALSE.

If set to FALSE, the server rejects all client requests to register eventnotifications with the extended result LDAP_UNWILLING_TO_PERFORM.

DefaultTRUE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdErrorLogDescription

Specifies the file path or device on the SecureWay Directory server machineto which error messages are written. On Windows, forward slashes areallowed, and a leading slash not preceded by a drive letter (such C:) isassumed to be rooted at the install directory, that is /tmp/slapd.errors =C:\Program Files\IBM\ldap\tmp\slapd.errors.


Default/tmp/slapd.errors


Maximum Length1024

Value Single-valued

ibm-slapdIncludeSchemaDescription

Specifies a file path on the SecureWay Directory server machine containingschema definitions. On Windows, forward slashes are allowed, and aleading slash not preceded by a drive letter (such as C:) is assumed to berooted at the install directory, that is, /etc/V3.system.at = C:\ProgramFiles\IBM\ldap\etc\V3.system.at.

Default

/etc/V3.system.at/etc/V3.system.oc/etc/V3.ibm.at/etc/V3.ibm.oc/etc/V3.user.at

/etc/V3.user.oc/etc/V3.ldapsyntaxes/etc/V3.matchingrules


Maximum Length1024

Value Multi-valued

ibm-slapdKrbAdminDNDescription

Specifies the kerberos ID of the LDAP administrator (for example,ibm-kn=admin1@realm1). Used when kerberos authentication is used toauthenticate the administrator when logged onto the Server Administrationinterface. This may be specified instead of or in addition to adminDN andadminPW.



Maximum Length128

Value Single-valued


ibm-slapdKrbEnableDescription

Specifies whether the server supports kerberos authentication. It must beeither TRUE or FALSE.

DefaultTRUE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdKrbIdentityMapDescription

Specifies whether to use kerberos identity mapping. It must be set to eitherTRUE or FALSE. If set to TRUE, when a client is authenticated with akerberos ID, the server searches for all local users with matching kerberoscredentials, and adds those user DNs to the bind credentials of theconnection. This allows ACLs based on LDAP user DNs to still be usablewith kerberos authentication.

DefaultFALSE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdKrbKeyTabDescription

Specifies the LDAP server kerberos keytab file. This file contains the LDAPserver private key, that is associated with its kerberos account. This file isto be protected (like the server SSL key database file).

On Windows, forward slashes are allowed, and any path not preceded bya drive letter (such as C:) is assumed to be rooted at the install directory(that is: /tmp/slapd.errors = C:\ProgramFiles\IBM\ldap\tmp\slapd.errors).



Maximum Length1024

Value Single-valued


ibm-slapdKrbRealmDescription

Specifies the kerberos realm of the LDAP server. It is used to publish theldapservicename attribute in the root DSE. Note that an LDAP server canserve as the repository of account information for multiple KDCs (andrealms), but the LDAP server, as a kerberos server , can only be a memberof a single realm.


SyntaxDirectory string with case-insensitive matching

Maximum Length256

Value Single-valued

ibm-slapdLdapCrlHostDescription

Specifies the host name of the LDAP server that contains the CertificateRevocation Lists (CRLs) for validating client x.509v3 certificates. Thisparameter is needed when ibm-slapdSslAuth=serverclientauth and theclient certificates have been issued for CRL validation.



Maximum Length256

Value Single-valued

ibm-slapdLdapCrlPasswordDescription

Specifies the password that server-side SSL uses to bind to the LDAPserver that contains the Certificate Revocation Lists (CRLs) for validatingclient x.509v3 certificates. This parameter might be needed whenibm-slapdSslAuth=serverclientauth and the client certificates have beenissued for CRL validation.

Note: If the LDAP server holding the CRLs permits unauthenticated accessto the CRLs (that is, anonymous access), then ibm-slapdLdapCrlPassword is not required.


SyntaxBinary

Maximum Length128

Value Single-valued


ibm-slapdLdapCrlPortDescription

Specifies the port used to connect to the LDAP server that contains theCertificate Revocation Lists (CRLs) for validating client x.509v3 certificates.This parameter is needed when ibm-slapdSslAuth=serverclientauth and theclient certificates have been issued for CRL validation. (IP ports areunsigned, 16-bit integers in the range 1 - 65535)


SyntaxInteger

Maximum Length5

Value Single-valued

ibm-slapdLdapCrlUserDescription

Specifies the bindDN that the server-side SSL uses to bind to the LDAPserver that contains the Certificate Revocation Lists (CRLs) for validatingclient x.509v3 certificates. This parameter might be needed whenibm-slapdSslAuth=serverclientauth and the client certificates have beenissued for CRL validation.

Note: If the LDAP server holding the CRLs permits unauthenticated accessto the CRLs (that is, anonymous access), then ibm-slapdLdapCrlUseris not required.


SyntaxDN

Maximum Length1000

Value Single-valued

ibm-slapdMasterDNDescription

Specifies the bind DN of master server. The value must match thereplicaBindDN in the replicaObject defined for the master server. Whenkerberos is used to authenticate to the replica, ibm-slapdMasterDN mustspecify the DN representation of the kerberos ID (for example,ibm-kn=freddy@realm1). When kerberos is used, MasterServerPW isignored.


SyntaxDN

Maximum Length512


Value Single-valued

ibm-slapdMasterPWDescription

Specifies the bind password of master replica server. The value must matchreplicaBindPW in the replicaObject defined for the master server. Whenkerberos is used, MasterServerPW is ignored.


SyntaxBinary

Maximum Length128

Value Single-valued

ibm-slapdMasterReferralDescription

Specifies the URL of the master replica server. For example:ldap://master.us.ibm.com

For security set to SSL only:ldaps://master.us.ibm.com:636

For security set to none and using a nonstandard port:ldap://master.us.ibm.com:1389

Defaultnone

SyntaxDirectory string wigh case-insensitive matching

Maximum Length256

Value Single-valued

ibm-slapdMaxEventsPerConnectionDescription

Specifies the maximum number of event notifications which can beregistered per connection.Minimum = 0 (unlimited)Maximum = 2,147,483,647

Default0

SyntaxInteger

Maximum Length11

Value Single-valued


ibm-slapdMaxEventsTotalDescription

Specifies the maximum total number of event notifications which can beregistered for all connections.Minimum = 0 (unlimited)Maximum = 2,147,483,647

Default0

SyntaxInteger

Maximum Length11

Value Single-valued

ibm-slapdMaxNumOfTransactionsDescription

Specifies the maximum number of transactions per server.Minimum = 0 (unlimited)Maximum = 2,147,483,647

Default20

SyntaxInteger

Maximum Length11

Value Single-valued

ibm-slapdMaxOpPerTransactionDescription

Specifies the maximum number of operations per transaction.Minimum = 0 (unlimited)Maximum = 2,147,483,647

Default5

SyntaxInteger

Maximum Length11

Value Single-valued

ibm-slapdMaxTimeLimitOfTransactionsDescription

Specifies the maximum timeout value of a pending transaction in seconds.Minimum = 0 (unlimited)Maximum = 2,147,483,647


Default300

SyntaxInteger

Maximum Length11

Value Single-valued

ibm-slapdPeerDNDescription

The bind DN of peer server. This setting allows this server to authenticateupdates received from peer servers. This setting requires that all updaterequests strictly adhere to special protocols.

Note: The ibm-slapdPeerDN defined for the server’s replica objects on theother peer servers must have this same value.

When kerberos is used to authenticate to the replica, ibm-slapdPeerDNmust specify the DN representation of the kerberos ID, for example,ibm-kn=freddy@realm1 .


SyntaxDN

Maximum Length512

Value Single-valued

ibm-slapdPeerPWDescription

The bind password of peer server. This setting allows this server toauthenticate updates received from peer servers. This setting requires thatall update requests strictly adhere to special protocols.

Note: The ibm-slapdPeerPW defined for the server’s replica objects on theother peer servers must have this same value.

When kerberos is used, ibm-slapdPeerPW is ignored.


SyntaxBinary

Maximum Length128

Value Single-valued

ibm-slapdPluginDescription

A plugin is a dynamically loaded library which extends the capabilities of


the server. An ibm-slapdPlugin attribute specifies to the server how to loadand initialize a plugin library. The syntax is:keyword filename init_function [args...]

The syntax is slightly different for each platform because of library namingconventions. Plugins shipped with SecureWay include:

AIXibm-slapdplugin: database /lib/libback-rdbm.a rdbm_backend_initibm-slapdplugin: preoperation /lib/libcl.a CLInit cn=changelog

Linuxibm-slapdplugin: database /lib/libback-rdbm.so rdbm_backend_initibm-slapdplugin: preoperation /lib/libcl.so CLInit cn=changelog

Solarisibm-slapdplugin: database /lib/libback-rdbm.so rdbm_backend_initibm-slapdplugin: preoperation /lib/libcl.so CLInit cn=changelog

Windowsibm-slapdplugin: database /bin/libback-rdbm.dll rdbm_backend_initibm-slapdplugin: preoperation /bin/libcl.dll CLInit cn=changelog

Most plugins are optional, but the RDBM backend plugin is required forall RDBM backends.

See the Server Plugin Reference for additional information.

Defaultdatabase /path/libback-rdbm.dll rdbm_backend_init


Maximum Length2000

Value Multi-valued

ibm-slapdPortDescription

Specifies the TCP/IP port used for non-SSL connections. It can not havethe same value as ibm-slapdSecurePort. (IP ports are unsigned, 16-bitintegers in the range 1 - 65535.)

Default389

SyntaxInteger

Maximum Length5

Value Single-valued


ibm-slapdPWEncryptionDescription

Specifies the encoding mechanism for the user passwords before they arestored in the directory. It must be specified as none, imask, crypt, or sha.

Defaultimask


Maximum Length5

Value Single-valued

ibm-slapdReadOnlyDescription

This attribute is normally applied to only the Directory backend. Itspecifies whether the backend can be written to. It must be specified aseither TRUE or FALSE. It defaults to FALSE if unspecified. If set to TRUE,the server returns LDAP_UNWILLING_TO_PERFORM (0x35) in responseto any client request which would change data in the readOnly database.

Note: If the machine is configured as a replica and ibm-slapdReadOnly isTRUE, the ibm-MasterDN still updates the directory, that is,replication continues to function.

DefaultFALSE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdReferralDescription

Specifies the referral LDAP URL to pass back when the local suffixes donot match the request. It is used for superior referral (that is, the suffix isnot within the naming context of the server).



Maximum Length32700

Value Multi-valued

ibm-slapdSchemaAdditionsDescription

The ibm-slapdSchemaAdditions attribute is used to identify explicitly


which file holds new schema entries. This is set by default to be/etc/V3.modifiedschema. If this attribute is not defined, the server revertsto using the last ibm-slapdIncludeSchema file as in previous releases.

Before Version 3.2, the last ″includeSchema″ entry in slapd.conf was thefile to which any new schema entries were added by the server if itrecieved an add request from a client. Normally the last ″includeSchema″is the V3.modifiedschema file, which is an empty file installed just for thispurpose.

Note: The name modified is misleading, for it only stores new entries.Changes to existing schema entries are made in their original files.

Default/etc/V3.modifiedschema


Maximum Length1024

Value Single-valued

ibm-slapdSchemaCheckDescription

Specifies the schema checking mechanism for the add/modify/deleteoperation. It must be specified as V2, V3, or V3_lenient.v V2 - Retain v2 and v2.1 checking. Recommended for migration purpose.v V3 - Perform v3 checking.v V3_lenient - Not all parent object classes are needed. Only the

immediate object class is needed when adding entries.

DefaultV3_lenient


Maximum Length10

Value Single-valued

ibm-slapdSecurePortDescription

Specifies the TCP/IP port used for SSL connections. It can not have thesame value as ibm-slapdPort. (IP ports are unsigned, 16-bit integers in therange 1 - 65535.)

Default636

SyntaxInteger

Maximum Length5

Value Single-valued


ibm-slapdSecurityDescription

Enables SSL connections. Must be none, SSL, or SSLOnly.v none - server listens on the non-ssl port only.v SSL - server listens on both the ssl and the non-ssl ports.v SSLOnly - server listens on the ssl port only.

Defaultnone


Maximum Length7

Value Single-valued

ibm-slapdSetenvDescription

The server runs putenv() for all values of ibm-slapdSetenv at startup tomodify the server runtime environment. Shell variables (like %PATH% or$LANG) are not expanded.

DB2CODEPAGE=1208 is required for unicode databases (this is setautomatically when you configure a unicode database using ServerAdministration, or using either of the ldapcfg or ldapxcfg commands).

setenv LDAP_CONCURRENTRW=ON turns off the locking that preventssearches from proceeding during updates. It allows for ’dirty reads’, that isresults that might not be consistent with the committed state of thedatabase.



Maximum Length2000

Value Multi-valued

ibm-slapdSizeLimitDescription

Specifies the maximum number of entries to return from search, regardlessof any size limit that might have been specified on the client search request(Range = 0...). If a client has passed a limit, then the smaller value of theclient values and the value read from slapd32.conf are used. If a client hasnot passed a limit and has bound as admin DN, the limit is consideredunlimited. If the client has not passed a limit and has not bound as adminDN, then the limit is that which was read from the slapd32.conf file. 0 =unlimited.

Default500


SyntaxInteger

Maximum Length12

Value Single-valued

ibm-slapdSslAuthDescription

Specifies the authentication type for the ssl connection, either serverauth orserverclientauth.v serverauth - supports server authentication at the client. This is the

default.v serverclientauth - supports both server and client authentication.

Defaultserverauth


Maximum Length16

Value Single-valued

ibm-slapdSslCertificateDescription

Specifies the label that identifies the server Personal Certificate in the keydatabase file. This label is specified when the server private key andcertificate are created with the gsk5ikm application. Ifibm-slapdSslCertificate is not defined, the default private key, as defined inthe key database file, is used by the LDAP server for SSL connections.



Maximum Length128

Value Single-valued

ibm-slapdSslCipherSpecsDescription

Specifies the decimal representation of a bitmask specifying the allowablekey encrytpion methods for establishing an SSL conection. Add the decimalvalues of all the desired encyption methods to determine the value ofibm-slapdSslCipherSpecs.

Table 7.

256 (0x0100) Triple DES encryption with a 168-bit key and a SHA-1 MAC(SLAPD_SSL_TRIPLE_DES_SHA_US)



512 (0x0200) DES encryption with a 56-bit key and a SHA-1 MAC(SLAPD_SSL_DES_SHA_US)

1024 (0x0400) RC4 encryption with a 128-bit key and a SHA-1 MAC(SLAPD_SSL_RC4_SHA_US)

2048 (0x0800) RC4 encryption with a 128-bit key and a MD5 MAC(SLAPD_SSL_RC4_MD5_US)

4096 (0x01000) RC2 encryption with a 40-bit key and a MD5 MAC(SLAPD_SSL_RC2_MD5_EXPORT)

8192 (0x02000) RC4 encryption with a 40-bit key and a MD5 MAC(SLAPD_SSL_RC4_MD5_EXPORT)

Default12288 (SLAPD_SSL_RC2_MD5_EXPORT +SLAPD_SSL_RC4_MD5_EXPORT)

SyntaxInteger

Maximum Length12

Value Single-valued

ibm-slapdSslKeyDatabaseDescription

Specifies the file path to the LDAP server SSL key database file. This keydatabase file is used for handling SSL connections from LDAP clients, aswell as for creating secure SSL connections to replica LDAP servers.

On Windows, forward slashes are allowed, and a leading slash notpreceeded by a drive specifier (such as C:) is assumed to be rooted at theinstall directory (that is, /etc/key.kdb = C:\ProgramFiles\IBM\ldap\etc\key.kdb).

Default/etc/key.kdb


Maximum Length1024

Value Single-valued

ibm-slapdSslKeyDatabasePWDescription

Specifies the password associated with the LDAP server SSL key databasefile, as specified on the ibm-slapdSslKeyDatabase parameter. If the LDAPserver key database file has an associated password stash file, then theibm-slapdSslKeyDatabasePW parameter can be ommitted, or set to none.

Note: The password stash file must be located in the same directory as thekey database file and it must have the same file name as the keydatabase file, but with an extension of .sth instead of .kdb.


Defaultnone

SyntaxBinary

Maximum Length128

Value Single-valued

ibm-slapdSuffixDescription

Specifies a naming context to be stored in this backend.


SyntaxDN

Maximum Length1000

Value Multi-valued

ibm-slapdSysLogLevelDescription

Specifies the level at which debugging and operation statistics are loggedin the slapd.errors file. It must be specified as l, m, or h.v h - high (provides the most information)v m - medium (the default)v l - low (provides the least information)

Defaultm


Maximum Length1

Value Single-valued

ibm-slapdTimeLimitDescription

Specifies the maximum number of seconds to spend on a search request,regardless of any time limit that might have been specified on the clientrequest. If a client has passed a limit, then the smaller value of the clientvalues and the value read from slapd32.conf are used. If a client has notpassed a limit and has bound as admin DN, the limit is consideredunlimited. If the client has not passed a limit and has not bound as adminDN, then the limit is that which was read from the slapd32.conf file. 0 =unlimited.

Default900


SyntaxInteger

Maximum Length

Value Single-valued

ibm-slapdTransactionEnableDescription

If the transaction plugin is loaded but ibm-slapdTransactionEnable is set toFALSE, the server rejects all StartTransaction requests with the responseLDAP_UNWILLING_TO_PERFORM.

DefaultTRUE

SyntaxBoolean

Maximum Length5

Value Single-valued

ibm-slapdUseProcessIdPwDescription

If set to TRUE, the server ignores the ibm-slapdDbUserID and theibm-slapdDbUserPW attributes and uses its own process credentials toauthenticate to DB2.

DefaultFALSE

SyntaxBoolean

Maximum Length5

Value Single-valued

objectClassDescription

The values of the objectClass attribute describe the kind of object which anentry represents.

SyntaxDirectory string

Maximum Length128

Value Multi-valued


Schema definitions that cannot be changedThe following schema definitions are required by the directory server. They mustnot be changed.

Object classes:

v accessGroupv accessRolev aliasv referralv replicaObjectv top

Attributes:

v aclEntryv aclPropagatev aclSourcev aliasedObjectName, aliasedentryNamev businessCategoryv cn, commonNamev createTimestampv creatorsNamev descriptionv dn, distinguishedNamev entryOwnerv memberv modifiersNamev modifyTimestampv namev o, organizationName, organizationv objectClassv ou, organizationalUnit, organizationalUnitNamev ownerv ownerPropagatev ownerSourcev refv replicaBindDNv replicaBindMethodv replicaCredentials, replicaBindCredentialsv replicaHostv replicaPortv replicaUpdateTimeIntervalv replicaUseSSLv seeAlso

Syntaxes:All


Matching Rules:All


Appendix C. Notices

This information was developed for products and services offered in the U.S.A.IBM might not offer the products, services, or features discussed in this documentin other countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter inthis document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the information. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thisinformation at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationDepartment LZKS11400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM’s suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

TrademarksThe following terms are trademarks of International Business MachinesCorporation in the United States, or other countries, or both:

AIX DB2 IBM SecureWay

Microsoft®, MS-DOS, Windows, and Windows NT are registered trademarks ofMicrosoft Corporation

Other company, product, and service names may be trademarks or service marksof others.


Glossary

Use this section to locate definitions of some ofthe IBM SecureWay Directory product terms

access control lists (ACLs)Access Control Lists (ACLs) provide ameans to protect information stored in anLDAP directory. Administrators use ACLsto restrict access to different portions ofthe directory, or specific directory entries.LDAP directory entries are related to eachother by a hierarchical tree structure. Eachdirectory entry (or object) contains thedistinguished name of the object as wellas a set of attributes and theircorresponding values.

access control groupsGroups to be used for access control. Eachgroup contains a multivalued attributeconsisting of member DNs. Access controlgroups have an object class of’AccessGroup’.

access permissionsThere are two sets of access permissions:v Permissions that apply to an entire

objectv Permissions that apply to attribute

access classes

aclEntryaclEntry is a multivalue attribute thatcontains information pertaining to theaccess allowed to the entry object andeach of its attributes. An aclEntry lists thefollowing types of information:v Who has rights to the entity object

(scope of the protection).v What classes of attributes the user has

access to (attribute access classes).v What rights the user or group has

(permission).

aclPropagateACLs can be set on any object in the tree.As is typical in a hierarchical file system,LDAP access control lists can propagatedown through the directory hierarchy.These ACLs, called propagating ACLs,have the aclPropagate attribute = true. Allchildren of this object now inherits theACL set at that point. In order to specify

an ACL different from that of its parent,this new ACL must be explicitly set.

aclSourceEach object has an associated aclSourceattribute. This contains the DN of theentry in which the ACL is defined. Thisattribute is kept by the server, but mightbe retrieved for administrative purposes.

aliasesAliases can be used within LDAP toreference entries anywhere within thedirectory tree. An alias is simply a pointerto another directory object.

Aliases Objects are of’objectclass=aliasObject’. The mandatoryattribute in this class,’aliasedObjectName’, contains the full dnof another directory object (the one towhich the alias refers). Since an aliaspoints to another section of a tree, it isnot possible to add a child object underan alias object.

By default, aliases objects are notdereferenced during a search operation.The client may request dereferencingusing a flag on the command line. Aliasesmay be dereferenced when locating thebase entry of the search. If the objectspecified as the base is an alias object, theobject will be derefenced before beginningthe search.

For example, an object with dn″cn=personOfTheWeek, o=Corporation,c=US″ which has the attributealiasedObjectName: ″cn=personA,o=Corporation,c=US″. With ’deref finding’set, a search base of″cn=personOfTheWeek, o=Corporation,c=US″ is dereferenced to ″cn=personA,o=Corporation,c=US″. This now becomesthe base for the search.

Another possibility is to dereferencealiases during searching. In this case, thedn used as the base is the one given bythe client, but alias entries found duringthe search are dereferenced.

An example of this might be a search for″cn=*week*″ with a base of


o=Corporation, c=US″. While the locatedNode is ″cn=personOfTheWeek,o=Corporation, c=US″ this object wouldbe dereferenced and the entry″cn=personA, o=Corporation,c=US″ isreturned as the search result.

A dereference of ’all’ might also be used.This means that alias entries aredereferenced both when locating thesearch base and when objects are foundduring the search operation.

attribute access classesAttributes requiring similar permissionfor access are grouped together in classes.Attributes are assigned to an access classwithin the slapd.at.* schema files. Thethree user-modifiable access classes are :v Normalv Sensitivev Critical

bulkloadA command line utility that is used forbulk-loading large amounts of data in ldifformat.

directory schemaEntries in a directory are made up of acollection of attributes and theirassociated values. Attributes mighty haveone or more values. In order to identify aparticular value in an entry, the attributetype name is specified along with thevalue, as in ″cn=John Doe″. This isreferred to as an attribute:value pair.Every entry contains an objectClassattribute that identifies what type ofinformation the entry contains. In fact, theobject class dictates which other attributesmay be present in an entry. The directoryschema defines the valid attribute typesand object classes that may appear in thedirectory. Attribute type definitions definethe maximum length and syntax of itsvalues. Object class definitions specifywhich attributes MUST be present in anobject of that class, as well as attributesthat might be present.

distinguished names (DNs)Every entry in a directory has adistinguished name (DN). The DN is thename that uniquely identifies an entry inthe directory. A DN is made up ofattribute:value pairs, separated bycommas, for example:

cn=Ben Gray,ou=editing,o=New York Times,c=UScn=Lucille White,ou=editing,o=New York Times,c=UScn=Tom Brown,ou=reporting,o=New York Times,c=US

LDAP DNs begin with the most specificattribute (usually some sort of name), andcontinue with progressively broaderattributes, often ending with a countryattribute. The first component of the DNis referred to as the RelativeDistinguished Name (RDN). It identifiesan entry distinctly from any other entriesthat have the same parent.

entryOwnerEach object has an associated entryOwnerattribute. The entryOwner attribute mightbe a user or a group, similar to what isallowed within the aclEntry. However, theentryOwner subject has certain privilegesover the object. Entry owners are inessence the administrators for particularobjects. They have full access on thatparticular object, similar to theadministrator DN. The administrator hasfull permission on any object in thedatabase.

groupsThere are two type of groups:v Normal groupsv Groups to be used for access control

Normal groups have an object class of’GroupOfNames’,’GroupOfUniqueNames’ or a user definedgroup. Access control groups have anobject class of ’AccessGroup’.

Each group object contains a multivaluedattribute consisting of member DNs.Groups cannot contain group DNs.

gsk4ikmThe gsk4ikm utility is used to createpublic-private key pairs and certificaterequests, receive certificate requests into akey database, and manage keys in a keydatabase. IKMGUI utilizes a graphicaluser interface. It provides you with theinformation you need to perform a task. Ifyou make an error, it issues a messageand prompts you again for theinformation.

indexing rulesIndex rules attached to attributes make itpossible to retrieve information faster. If


only the attribute is given, all possibleindexes are maintained. IBM SecureWayDirectory provides the following indexingrules:v Equalv Approximatev Substring

See “Appendix A. Indexing rules” onpage 115.

ldapaddThe LDAP modify-entry and LDAPadd-entry tool ldapmodify is ashell-accessible interface to theldap_modify and ldap_add library calls.ldapadd is implemented as a renamedversion of ldapmodify. When invoked asldapadd the -a (add new entry) flag isturned on automatically.

ldapdeleteThe LDAP delete-entry tool ldapdelete isa shell-accessible interface to theldap_delete library call. ldapdelete opensa connection to an LDAP server andbinds and deletes one or more entries. Ifone or more dn arguments are provided,entries with those Distinguished Names(DN) are deleted. Each DN should be astring-represented DN.

ldapmodifyThe LDAP modify-entry and LDAPadd-entry tools ldapmodify is ashell-accessible interface to theldap_modify and ldap_add library calls.ldapadd is implemented as a renamedversion of ldapmodify. When invoked asldapadd the -a (add new entry) flag isturned on automatically.

ldapmodrdnLDAP modify-entry RDN toolldapmodrdn is a shell-accessible interfaceto the ldap_modrdn library call.ldapmodrdn opens a connection to anLDAP server and binds and modifies theRDN of entries. The entry information isread from standard input, from a file,through the use of the - f option, or fromthe command-line pair DN and RDN.

ldapsearchThe LDAP search tool ldapsearch is ashell-accessible interface to theldap_search library call. ldapsearch opensa connection to an LDAP server and

binds and performs a search using thefilter filter. The filter should conform tothe string representation for LDAP filters.

ldif LDIF is used to represent LDAP entries intext form. The purpose of this informationis to describe the LDAP Data InterchangeFormat (LDIF), as used by theldapmodify, ldapadd, and ldapsearchcommand-line utilities.

The LDIF tool ldif is a shell-accessibleutility that converts arbitrary data valuesto LDIF. It reads input values fromstandard input and produces LDIF.

ldif2dbThis program is used to load entriesspecified in text LDAP DirectoryInterchange Format (LDIF) into adirectory stored in a relational database.The database must already exist. ldif2dbcan be used to add entries to an emptydirectory database or to a database thatalready contains entries.

matching rulesMatching rules describe how to perform acomparison. Supported matching rulesare:caseExactIA5MatchcaseExactMatchcaseExactOrderingMatchcaseExactSubstringsMatchcaseIgnoreIA5MatchcaseIgnoreMatchcaseIgnoreOrderingMatchcaseIgnoreSubstringsMatchdistinguishedNameMatchdistinguishedNameOrderingMatchgeneralizedTimeMatchgeneralizedTimeOrderingMatchintegerFirstComponentMatchintegerMatchobjectIdentifierFirstComponentMatchobjectIdentifierMatchoctetStringMatchtelephoneNumberMatchtelephoneNumberSubstringsMatchuTCTimeMatch

multiple valuesMultiple values are used to assign morethan one value to an attribute. The pencil

icon indicates the attribute can havemultiple values, for example, toaccommodate a maiden and married lastname. To add multiple values to anattribute, click the pencil icon, then add

Glossary 151

one value per line. If an attribute containsmultiple values, the field displays as adrop-down list.

object class definitionsEvery entry contains an objectClassattribute that identifies what type ofinformation the entry contains. The objectclass dictates which other attributes canbe present in an entry. The directoryschema defines the valid attribute typesand object classes that can appear in thedirectory. Attribute type definitions definethe maximum length and syntax of itsvalues. Object class definitions specifywhich attributes MUST be present in anobject of that class, as well as attributesthat might be present.

object class typesObject classes can be structural, forexample, person; abstract, for exampletop; or auxiliary, for example ePerson.

ownerPropagateOwner propagation works exactly thesame as ACL Propagation. By default,owners are inherited down the hierarchytree, and their owner propagate attributeis set to true. If set to false, the ownerbecomes an override, pertaining only tothis particular object.

ownerSourceEach object also has an associatedownerSource attribute. This contains theDN of the entry in which the ownervalues are defined. This attribute is keptby the server but can be retrieved foradministrative purposes.

referralsReferrals provide a way for servers torefer clients to additional directoryservers. With referrals you can:v Distribute namespace information

among multiple serversv Provide knowledge of where data

resides within a set of interrelatedservers

v Route client requests to the appropriateserver

The general format for a referral is:ldap[s]://hostname:port. Typically theformat for a referral to a nonsecure serveris: ldap://hostname:389 and to a secureSSL server is: ldaps://hostname:636. See

“Working with referrals” on page 44 foradditional information.

relative distinguished name (RDN)The relative distinguished name (RDN) isthe first component of the distinguishedname (DN). For example, if the entriesDN is cn=John Doe,ou=Test,o=IBM,c=US,the RDN is cn=John Doe.

replicasA replica is a server that runs a copy ofthe directory. This replicated server cankeep a copy of the entire directory or justone tree of that directory. Any update to areplica server is referred to the masterserver. If the master server fails, you havea copy of the directory trees on the replicaserver. Using the replica server alsoimproves the response time.

roles Roles are like groups, but contain specialpermissions granted by the Administrator.

Secure Sockets Layer (SSL)The IBM SecureWay Directory server hasthe ability to protect LDAP access withSecure Sockets Layer security. When usingSSL to secure LDAP communications withthe IBM SecureWay Directory server, theSSL authentication mechanism known asserver authentication is used.

suffixesA suffix is a DN that identifies the topentry in a locally held directory hierarchy.Because of the relative naming schemeused in LDAP, this DN is also the suffixof every other entry within that directoryhierarchy. A directory server might havemultiple suffixes, each identifying alocally held directory hierarchy.

SyntaxSyntax refers to the required format fordata. Supported syntaxes are:IBM Attribute Type Description

Matching Rule DescriptionName Form DescriptionAttribute Type DescriptionObject Class DescriptionDIT Structure Rule DescriptionDIT Content Rule DescriptionLDAP Syntax DescriptionOIDMatching Rule Use DescriptionBoolean - TRUE/FALSEBinary - octet stringINTEGER - integral numberGeneralized TimeIA5 String - case-sensitive string


Directory String - case-insensitive stringUTC timeTelephone NumberDN - distinguished name

Glossary 153

Index

Aaccess controls

dynamic configuration 67ACLs

change log 40adding

replicas 28adding a large number of members 58administration

name 25password 25utilities

change log 43associating

servers with referrals 45attribute types

schema file 63authentication

client 98

Bbacking up a directory 29bulkload 56

alternative to 58

Cchange log

access control 40ACLs 40administration

utilities 43configuring 38confuguration

multiple databases 39expiration of entries 40schema 40

logging of changes 39change tables 33changeLogEntry 41

attributes 41examples 43

chatacter setIANA 36

checkingentries 66

clientsystem requirements 1

client authentication 98client utilities

ldapadd 54ldapdelete 53ldapmodify 54ldapmodrdn 54ldapsearch 54

code pageDB2 36

commands 53bulkload 56

commands (continued)db2ldif 59ldapadd 54ldapdelete 53ldapmodify 54ldapmodrdn 54ldapsearch 54ldif 54ldif2db 56

configurationdatabase 7replica

general 28simple 26

schema 117copying

master 29replica 29

creatingreplicas 28

Ddatabase

backing up 34configuration 7DB2 7importing entries 35optimizing 35required levels 1settings 34UTF-8

creating 36db2

required levels 1DB2 7, 34

code page 36DB2 database 7db2ldif 59DEN 70directory

backing up 29population

for a replica 29directory-enabled network

schema support 70disallowed changes

schema 65disk space

requirements 1distinguished name 49

pseudo 50DN 49dynamic

changesschema 64

schema 68dynamic configuration

access controls 67replication 67

dynamic schemachanges 64matching rules 69syntaxes 68

Eencryption 1entries

change log expiration 40entry checking

against schema 66error logs 48examples

changeLogEntry 43ldapsearch 42

Ggeneral configuration 28generalized time 70GSKit 1

installation 4removing 5uninstalling 5

IIANA 36IBMAttributeTypes 62IBMsubschema 61installation

client 3, 4server 3, 4

installation packages 3

Kkey database 97

Lldapadd 54ldapdelete 30, 53ldapmodify 30, 54ldapmodrdn 54ldapsearch 30, 54

examples 42ldif 54ldif2db 56listing

replicas 30locale 36logs

errors 48


Mmatching rules 69

Nnamespace 46national language characters 35Netscape

compatibility 67grammar 67

Oobject class

changeLogEntry 41IBMAttributeTypes 62IBMsubschema 61

Ppackages

installation 3passwords

administration 25populating

replicas 29pseudo DNs 50

Qqueries

schema 64

Rref attribute 44referral

object class 44ref attribute 44

referrals 44default

defining 46distributing the namespace 46entries 44server association 45

removingreplicas 30

replicaconfiguration

general 28simple 26

creating servers 25editing 30synchronization

cleaning change tables 33resynchronizing 33verifying 32

replicasadding 28creating 28listing 30removing 30

replicationdynamic configuration 67

SSASL 98schema

attribute types 63change log 40changes

disallowed 65checking 65common

support 61configuration 117dynamic 68

changes 64file

attribute types 63queries 64subschema entries 61

SecureWay Directoryremoving 23starting 22stopping 22

securityclient setup 97GSKit 1SASL 93SSL 1, 93

serversystem requirements 1

server utilitiesbulkload 37, 56db2ldif 37, 59ldif 54ldif2db 37, 56

simple configuration 26slapd 22slapd32.conf 25, 38SSL 1, 93, 98starting 22stopping 22subclassing 69subschema entries 61suffixes 25synchronization of replicas 33syntax

Backus Naur Form 49distinguished name 49

special characters 50system requirements

client 1database 1disk space 1RAM

client 1server 1

Ttime

generalized 70UTC 70

UUTC time 70UTF-8 35

utilitiesclient 53command line 53

bulkload 56db2ldif 59ldapadd 54ldapdelete 53ldapmodify 54ldapmodrdn 54ldapsearch 54ldif 54ldif2db 56

server 54bulkload 37db2ldif 37ldif2db 37


��

Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

publib.boulder.ibm.compublib.boulder.ibm.com/tividd/td/ibmds/sparent322/en_us/pdf/lparent.pdf ·...

Documents