IBM Directory Server Version 5.1: Administration Guide

First Edition (November 2002)

This edition applies to version 5, release 1, of the IBM^(R) Directory Server and to all subsequent releases and modifications until otherwise indicated in new editions.

(C) Copyright International Business Machines Corporation 2002. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Preface

This document contains the information that you need to administer the IBM Directory Server.

Contents

Directory overview

Server Administration

Directory Management

User-related tasks

Command line utilities

Appendixes

Directory overview

Defining a directory

A directory is a collection of information about objects arranged in a hierarchical structure. It is a specialized database, that enables users or applications to find resources that have the characteristics needed for a particular task.

If the name of an object is known, its characteristics can be retrieved. If the name of a particular individual object is not known, the directory can be searched for a list of objects that meet a certain requirement. Directories can usually be searched by specific criteria, not just by a predefined set of categories.

A directory is a specialized database that has characteristics that set it apart from general purpose relational databases. A characteristic of a directory is that it is accessed (read or searched) much more often than it is updated (written). Because directories must be able to support high volumes of read requests, they are typically optimized for read access. Because directories are not intended to provide as many functions as general-purpose databases, they can be optimized to economically provide more applications with rapid access to directory data in large distributed environments.

A directory can be centralized or distributed. If a directory is centralized, there is one directory server (or a server cluster) at one location that provides access to the directory. If the directory is distributed, there are more than one server, usually geographically dispersed, that provide access to the directory.

When a directory is distributed, the information stored in the directory can be partitioned or replicated. When information is partitioned, each directory server stores a unique and non-overlapping subset of the information. That is, each directory entry is stored by one and only one server. The technique to partition the directory is to use LDAP referrals. LDAP referrals allow the users to refer Lightweight Directory Access Protocol (LDAP) requests to either the same or different name spaces stored in a different (or same) server. When information is replicated, the same directory entry is stored by more than one server. In a distributed directory, some information may be partitioned, and some information may be replicated.

Directory clients and servers

Directories are usually accessed using the client-server model of communication. The client and server processes might or might not be on the same machine. A server is capable of serving many clients. An application that wants to read or write information in a directory does not access the directory directly. Instead, it calls a function or application programming interface (API) that causes a message to be sent to another process. This second process accesses the information in the directory on behalf of the requesting application. The results of the read or write are then returned to the requesting application.

An API defines the programming interface a particular programming language uses to access a service. The format and contents of the messages exchanged between client and server must adhere to an agreed upon protocol. LDAP defines a message protocol used by directory clients and directory servers. There is also an associated LDAP API for the C language and ways to access the directory from a Java^(TM) application using the Java Naming and Directory Interface (JNDI).

Directory security

A directory should support the basic capabilities needed to implement a security policy. The directory might not directly provide the underlying security capabilities, but it might be integrated with a trusted network security service that provides the basic security services. First, a method is needed to authenticate users. Authentication verifies that users are who they say they are. A user name and password is a basic authentication scheme. Once users are authenticated, it must be determined if they have the authorization or permission to perform the requested operation on the specific object.

Authorization is often based on access control lists (ACLs). An ACL is a list of authorizations that may be attached to objects and attributes in the directory. An ACL lists what type of access each user or a group of users is allowed or denied. In order to make ACLs shorter and more manageable, users with the same access rights are often put into groups.

The IBM Directory

The IBM Directory implements the Internet Engineering Task Force (IETF) LDAP V3 specifications. It also includes enhancements added by IBM in functional and performance areas. This version uses the IBM DB2^(R) as the backing store to provide per LDAP operation transaction integrity, high performance operations, and on-line backup and restore capability. It interoperates with the IETF LDAP V3 based clients. Major features include:

• Administration and configuration for the IBM Directory is provided by a Graphical User Interface (GUI). The administration and configuration functions allow the administrator to:
  • Perform the initial setup of the directory
  • Change configuration parameters and options
  • Manage the daily operations of the directory, such as adding or editing objects, for example, object classes, attributes, and entries.
• A dynamically extensible directory schema - This means that administrators can define new attributes and object classes to enhance the directory schema. Changes can be made to the directory schema, too, which are subject to consistency checks. Users may dynamically modify the schema content without restarting the directory server. Since the schema itself is part of the directory, schema update operations are done through standard LDAP APIs. The major functions provided by LDAPv3 dynamic extensible schema are:
  • Queriable schema information through LDAP APIs
  • Dynamic schema changes through LDAP APIs
  • Server rootDSE
  • Dynamic configuration changes using LDAP APIs
• UTF-8 (Universal Character Set Transformation Format) - An IBM Directory Server supports data in multiple languages, and allows users to store, retrieve and manage information in a native language code page.
• Simple Authentication and Security Layer (SASL) - This support provides for additional authentication mechanisms. The Secure Sockets Layer (SSL) provides encryption of data and authentication using X.509v3 public-key certificates. A server may be configured to run with or without SSL support.
• Replication - Replication is supported, which makes additional read-only copies of the directory available, improving performance and reliability of the directory service.
• Referrals - Support for LDAP referrals, allowing directories to be distributed across multiple LDAP servers where a single server may only contain a subset of the whole directory data.
• Access control model - A powerful, easy-to-manage access control model is supported through ACLs.
• Change log
• Password policy
• Security audit logging

Server Administration

Web Administration graphical user interface (GUI)

The preferred method of administering the server is by using the Web Administration GUI.

Directory administration daemon

The directory administration daemon enables remote management of the IBM Directory Server. It must be installed on the machine where the IBM Directory Server is installed and be running continuously. The directory administration daemon accepts requests by way of LDAP extended operations and supports starting, stopping, restarting and status monitoring of the IBM Directory Server. By default, the IBM Directory administration daemon listens on two ports, port 3538 for non-SSL connections and port 3539 for SSL connections, if SSL communication is enabled.

Note:

If you enable SSL communication, the directory administration daemon must be stopped and restarted for SSL to take effect. See Configuring SSL settings.

Setting up Web Administration

Unlike the previous releases in which the Server Administration GUI had to be installed on the same machine as the directory server, the IBM Directory Server Version 5.1 Web Administration tool is installed on an application server, such as the embedded version of IBM WebSphere^(R) Application Server - Express included with the IBM Directory Server, and administered through a console. Servers that have been added to the console can utilize the Web Administration tool without having to have the tool installed.

Note:

The embedded version of IBM WebSphere Application Server - Express does not support HP-UX systems. HP-UX must use another application server, such as Apache Tomcat/4.0.4.

Prerequisites

Before you can start using the Web Administration Tool, ensure that you have the completed the following prerequisites during the configuration of your server:

• Set the AdminDN and password.
• Configured a database.

See the IBM Directory Server Version 5.1 Installation and Configuration Guide for information on these tasks.

Notes:

1. The administration daemon must be running. Issue the command ibmdiradm to start the daemon, or additionally on Windows-based systems you can start the administration daemon using the Services panel.

2. If you have other Web server applications running, ensure that the Web Administration Tool is not running on the same port as the other Web servers.

Logging on to the console

If you have installed the Web Administration package start the application server. For the embedded version of IBM WebSphere Application Server - Express go to the directory where you installed the IBM Directory Server and issue the command:

For UNIX-based platforms

<IDSinstalldir>/ldap/appsrv/bin/startServer.sh server1 

Note:

For Solaris this is opt/ibmldapc/appsrv/bin/startServer.sh server1

For Windows-based platforms

<IDSinstalldir>\ldap\appsrv\bin\startServer.bat server1 

Open a Web browser and type the following address: http://localhost:9080/IDSWebApp/IDSjsp/Login.jsp. The IBM Directory Server Web Administration login page panel is displayed.

1. Log in as Console Admin, the default selection in the LDAP Hostname field.
2. In the Username field type: superadmin.
3. In the Password field type: secret.
4. Click Login.

The IBM Directory Server Web Administration Tool panel is displayed.

Managing the console

At the IBM Directory Server Web Administration Tool panel:

1. Expand Console administration in the navigation area. Use

   Change console administrator login

   to change superadmin to a different administrator ID.

   1. Enter the new administrator ID.

      Note:

      Only one administrator ID is allowed. The superadmin ID is replaced by the new ID that you specified.

   2. Enter the current administrator password. The password, secret, is the same for the new administrator ID, until you change it

   Change console administrator password

   to change the administrator password, secret, to another password.

   1. Enter the current password.
   2. Enter the new password.
   3. Reenter the new password to confirm that their are no typographical errors.
   4. Click OK.

   Manage console servers

   to add, edit, or delete servers in the console. Click Manage console servers in the navigation area. A listing of server host names and port numbers is displayed. You can:

   Add a server to the console

   1. Click Add.
   2. Enter the host name address. For example myserver.mycity.mycompany.com
   3. Specify the port numbers or accept the defaults.
   4. Specify if the server is SSL enabled.
   5. Click OK to apply the changes or click Cancel to exit the panel without making any changes.

   Modify a server in the console

   1. Select the radio button by the server you want to modify.
   2. Click Edit.
   3. You can change the port numbers.
   4. You can change whether the server is SSL enabled.
   5. Click OK to apply the changes or click Cancel to exit the panel without making any changes.

   Remove a server from the console

   1. Select the radio button by the server you want to remove.
   2. Click Delete.
   3. Click OK to delete the server or click Cancel to exit the panel without making any changes.

   Manage console properties

   to set the following:

   • Component management - enables the selected components for all servers in the console. By default all the components are enabled.
   • Session properties - sets the time out limit for the console session. The default setting is 60 minutes.
   • SSL key database - enables you set up the console so that it can communicate with other LDAP servers using the Secure Sockets Layer (SSL), if necessary. Set the key database path and file name, the key password, the trusted database path and file name, the trusted password in the appropriate fields. Jks is the supported file type. See Using gsk6ikm and Secure Sockets Layer for information about key databases and SSL.

2. When you have finished setting up the console, click Logout to exit.

Starting the Web Administration

At the Logout successful panel that is displayed when you exit Console administrator, you see the message:

If you have been accidentally logged out then you will need to re-login 
by clicking here. 

Click the word here to go to the IBM Directory Server Web Administration Login Page.

Logging on to the Web Administration Tool

• At the IBM Directory Server Web Administration login page select the LDAP host name for your machine from the drop-down menu.
• Enter the DN and the password for that server (you set these up during the server installation process).
• Click Login.

After the tool has been started, the application window has five parts:

Banner area

The banner area located at the top of the panel contains the application name, IBM Directory Server Web Administration Tool, and the IBM Logo.

Navigation area

The navigation area, located on the left side of the panel, displays expandable categories for various server content tasks.

Work area

The work area displays the tasks associated with the selected task in the navigation area. For example, if Managing server security is selected in the navigation area, the work area displays the Server Security page and the tabs containing tasks related to setting up server security.

Server status area

The server status area, located at the top of the work area, indicates the status and the name of the server being administered. It also has two icon links, one to the Start/Stop/Restart procedure and the other to general help information. When you select a task from the navigation area, the name of the selected task, a link to the error log files, and a link to the task help are also displayed.

Task status area

The task status area, located beneath the work area, displays the status of the current task.

Distinguished names (DNs)

Every entry in the directory has a distinguished name (DN). The DN is the name that uniquely identifies an entry in the directory. A DN is made up of attribute=value pairs, separated by commas, for example:

cn=Ben Gray,ou=editing,o=New York Times,c=US
cn=Lucille White,ou=editing,o=New York Times,c=US
cn=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 a DN. The order of the component attribute value pairs is important. The DN contains one component for each level of the directory hierarchy from the root down to the level where the entry resides. LDAP DNs begin with the most specific attribute (usually some sort of name), and continue with progressively broader attributes, often ending with a country attribute. The first component of the DN is referred to as the Relative Distinguished Name (RDN). It identifies an entry distinctly 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. The attribute:value pair making up the RDN for an entry must also be present in the entry. (This is not true of the other components of the DN.)

Follow this example to create a distinguished name in the ibmslapd.conf file:

DN: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
ibm-slapdDbName: <databasename>
ibm-slapdUserID: <username> 
ibm-slapdDbUserPW: <password>
ibm-slapdDbInstance: <username>

Distinguished name syntax

The Distinguished Name (DN) syntax supported by this server is based on RFC 2253. 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
 
   <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 or semicolon. The white-space characters are ignored, and the semicolon is replaced with 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, which are not part of the value. Inside the quoted value, the following characters can occur without any escaping:

• A space or "#" character occurring at the beginning of the string
• A space character occurring at the end of the string
• 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 listed previously and the double quotation marks ('"' ASCII 34) character.

This notation is designed to be convenient for common forms of names. The following example is a distinguished name written using this notation. First is a name containing three components. The first of the components is a multivalued RDN. A multivalued RDN contains more than one attribute:value pair and can be used to distinctly identify a specific entry in cases where a simple CN value might be ambiguous:

OU=Sales+CN=J. Smith,O=Widget Inc.,C=US

DN escaping rules

A DN can contain special characters. These characters are , (comma), = (equals), + (plus), < (less than), > (greater than), # (number sign), ; (semicolon), \ (backslash), and "" (quotation marks).

To escape these special characters or other characters in an attribute value in a DN string, use the following methods:

1. If a character to be escaped is one of special characters, precede it by a backslash ('\' ASCII 92). This example shows a method of escaping a comma in an organization name:

   CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB
   

   This is the preferred method.

2. Otherwise replace the character to be escaped by a backslash and two hex digits, which form a single byte in the code of the character. The code of the character must be in UTF-8 code set.

   CN=L. Eagle,O=Sue\2C Grabbit and Runn,C=GB
   

3. Surround the entire attribute value by "" (quotation marks) (ASCII 34), that are not part of the value. Between the quotation character pair, all characters are taken as is, except for the \ (backslash). The \ (backslash) can be used to escape a backslash (ASCII 92) or quotation marks (ASCII 34), any of the special characters previously mentioned, or hex pairs as in method 2. For example, to escape the quotation marks in cn=xyz"qrs"abc, it becomes cn=xyz\"qrs\"abc or to escape a \:

   "you need to escape a single backslash this way \\" 
    
   

   Another example, "\Zoo" is illegal, because 'Z' cannot be escaped in this context.

On the server end, when a DN is received in this form, the server reformats the DN using escape mechanisms number 1 and 2 for internal processing.

Pseudo DNs

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

Three pseudo DNs are supported by LDAP version 3:

• access-id: cn=this

  When specified as part of an ACL, this DN refers to the bindDN, which matches the DN on which the operation is performed. For example, if an operation is performed 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 of those given to "cn=this" and those given to "cn=personA, ou=IBM, c=US".

• group: cn=anybody

  When specified as part of an ACL, this DN refers to all users, even those that are unauthenticated. Users cannot be removed from this group, and this group cannot be removed from the database.

• group: cn=Authenticated

  This DN refers to any DN that has been authenticated by the directory. The method of authentication is not considered.

  Note:

  "cn=Authenticated" refers to a DN that has been authenticated anywhere on the server, regardless of where the object representing the DN is located. It should be used with caution, however. For example, under one suffix, "cn=Secret" could be a node called "cn=Confidential Material" which has an aclentry of "group:cn=Authenticated:normal:rsc". Under another suffix, "cn=Common" could be the node "cn=Public Material". If these two trees reside on the same server, a bind to "cn=Public Material" would be considered authenticated, and would get permission to the normal class on the "cn= Confidential Material" object.

Some examples of pseudo DNs:

Example 1

Consider the following ACL for object: cn=personA, c=US AclEntry:

access-id: cn = this:critical:rwsc  
AclEntry: group: cn=Anybody: normal:rsc  
AclEntry: group: cn=Authenticated: sensitive:rcs

Table 1.

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 2

Consider the following ACL for object: cn=personA, c=US AclEntry: access-id:cn=personA, c=US: object:ad

AclEntry: access-id: cn = this:critical:rwsc  
AclEntry: group: cn=Anybody: normal:rsc  
AclEntry: group: cn=Authenticated: sensitive:rcs

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

Table 2.

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

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 group permissions are not given because there is a more specific aclentry ("access-id:cn=personA, c=US") for the bind DN ("cn=personA, c=US").

Enhanced DN processing

A composite RDN of a DN may consist of multiple components connected by the '+' operators. The server enhances the support for searches on entries that have such a DN. A composite RDN can be specified in any order as the base for a search operation.

ldapsearch cn=mike+ou=austin,o=ibm,c=us

The server accepts DN normalization extended operations. DN normalization extended operations normalize DNs using the server schema. This extended operation might be useful for applications that use DNs. See the IBM Directory Server Version 5.1 C-client Programming Reference for more information.

Basic server tasks

The following tasks can be performed by the directory administrator:

Changing an administrator distinguished name and password

The administrator name and password is usually set during the server installation and configuration process. However, you can change an administrator name and an administrator password by using either the Web Administration Tool or the command line.

Using Web Administration:

Click User properties in the navigation area of the Web Administration Tool. Two selections are displayed:

Change administrator login

Specify a new Administrator DN in the field and enter the current password. Click OK or click Cancel to return to the Welcome panel without making any changes.

Note:

This selection is available only if you are logged in as the administrator. It is not available if you are logged in as a user.

Change password

To change the password for the currently logged-in DN, type your current password in the Current password field. Then type your new password in the New password field and type it again in the Confirm new password field and click OK. Click Cancel to return to the Welcome panel without making any changes.

Using the command line:

You can use either the ldapcfg command or the ldapxcfg utility from the command line.

Using the ldapcfg command:

ldapcfg -u <admindn> -p <adminpassword>
 

To use the ldapxcfg utility type ldapxcfg on a command line. When the IBM Directory Server Configuration Tool panel is displayed select Administrator DN/password and follow the directions. See the IBM Directory Server Version 5.1 Installation and Configuration Guide for additional information on using the ldapxcfg utility.

See Distinguished names (DNs) for more information about distinguished names.

Checking server status

You can check the status of the server by searching for the object classes under cn=monitor. To do this, use one of the following methods:

Using Web Administration:

Expand the Server administration category in the navigation area. Click View server status. If the directory server is running, the following information is displayed:

Hostname

The host name of the LDAP server.

Server status

The server is either Running, Stopped, or Running configuration only mode. You can determine the server status at any time by the three icons displayed in the left side corner of the server status area.

Start time

The time the server was started. The start time is in the format:

year-month-day hour:minutes:seconds GMT 

Note:

If expressed in local time the format is

day-month-date hour:minutes:seconds timezone year

Current time

The current time on the server. The current time is in the format:

year month day hour:minutes:seconds GMT
 

Note:

If expressed in local time the format is

day month date hour:minutes:seconds timezone year

Total threads

The number of worker threads being used by the server.

Total threads blocked on write

The number of threads sending data back to the client.

Total threads blocked on read

The number of threads reading data from the client.

Number of connections

The number of currently active connections.

Total connections

The total number of connections since the server was started.

Number of operations initiated

The number of initiated requests since the server was started.

Number of operations completed

The number of completed requests since the server was started.

Number of searches initiated

The number of initiated searches since the server was started.

Number of searches completed

The number of completed searches since the server was started.

Number of entries sent

The number of entries sent by the server since the server was started.

Percentage of entry cache used

The percentage of entry cache currently used. This value does not display in configuration only mode.

Percentage of search filter cache used

The percentage of search filter cache currently used. This value does not display in configuration only mode.

ACL cache

A Boolean value indicating that the ACL cache is active (TRUE) or inactive (FALSE). This value does not display in configuration only mode.

Maximum ACL cache size

The maximum number of entries in the ACL cache. This value does not display in configuration only mode.

Note:

When a link is clicked in the navigation area a new connection is opened to the LDAP server. The number of connections increases, if a link is clicked repeatedly in the navigation area. These connections are closed only when the Java garbage collector begins its cleanup.

Using the command line:

ldapsearch -h <servername> -p <portnumber> -b cn=monitor -s base objectclass=*

This command returns the following information:

cn=monitor

version=IBM Directory, Version 5.1

total connections

The total number of connections since the server was started.

current connections

The number of active connections.

maxconnections

The maximum number of active connections allowed.

writewaiters

The number of threads sending data back to the client.

readwaiters

The number of threads reading data from the client.

opsinitiated

The number of initiated requests since the server was started.

livethreads

The number of worker threads being used by the server.

opscompleted

The number of completed requests since the server was started.

entriessent

The number of entries sent by the server since the server was started.

searchesrequested

The number of initiated searches since the server was started.

searchescompleted

The number of completed searches since the server was started.

filter_cache_size

The maximum number of filters allowed in the cache.

filter_cache_current

The number of filters currently in the cache.

filter_cache_hit

The number of filters found in the cache.

filter_cache_miss

The number of filters not found in the cache.

filter_cache_bypass_limit

Search filters that return more entries than this limit are not cached.

entry_cache_size

The maximum number of entries allowed in the cache.

entry_cache_current

The number of entries currently in the cache.

entry_cache_hit

The number of entries found in the cache.

entry_cache_miss

The number of entries not found in the cache.

acl_cache

A Boolean value indicating that the ACL cache is active (TRUE) or inactive (FALSE).

acl_cache_size

The maximum number of entries in the ACL cache.

currenttime

The current time on the server. The current time is in the format:

year month day hour:minutes:seconds GMT
 

Note:

If expressed in local time the format is

day month date hour:minutes:seconds timezone year

starttime

The time the server was started. The start time is in the format:

year month day hour:minutes:seconds GMT 

Note:

If expressed in local time the format is

day month date hour:minutes:seconds timezone year

en_currentregs

The current number of client registrations for event notification.

en_notificationssent

The total number of event notifications sent to clients since the server was started.

Checking connection status

Perform the following to check the connection status of the server.

Using Web Administration:

Click View server connections in the navigation area. A table containing the following information is displayed:

DN

Specifies a list of all the DNs connected to the server.

Start time

Specifies the date and time when the connections were made.

Status

Specifies whether the connection is active or idle. A connection is considered active if it has any operations in progress.

Operations initiated

Specifies the number of operations requested since the connection was established.

Operations completed

Specifies the number of operations that have been completed for each connection.

Notes:

1. This table displays up to 20 connections at a time.

2. When a link is clicked in the navigation area a new connection is opened to the LDAP server. The number of connections increases, if a link is clicked repeatedly in the navigation area. These connections are closed only when the Java garbage collector begins its cleanup.

Using the command line:

ldapsearch -D<adminDN> -w <adminPW> -h <servername> -p <portnumber> 
          -b cn=connections,cn=monitor -s base objectclass=*

This command returns information in the following format:

cn=connections,cn=monitor
connection=1632 : 2002-10-05 19:18:21 GMT  : 1 : 1 : CN=ADMIN : 
connection=1487 : 2002-10-05 19:17:01 GMT  : 1 : 1 : CN=ADMIN : 

Starting and stopping the server

You can use either of the following methods to start or stop the server.

Using Web Administration:

Note:

The Admin daemon must be running.

The current status of the server, either started, stopped or started in configuration mode, is indicated by the icons in the upper left-hand corner of the server status area. The current status is also described in the first sentence of the work area, for example

The Directory Server is currently running

1. If you have not done so already, click Server Administration in the Web Administration navigation area and then click Start/Stop/Restart Server in the expanded list.
2. The message area displays the current state of the server (stopped, running, or running in configuration only mode). Depending on the state of the server, running or stopped, buttons are enabled for you to change the state of the server.
   

   Table 3.
   

   Server status	Buttons available
   Stopped	Start, Close
   Running	Stop, Restart, Close
   Running in configuration only mode	Stop, Restart, Close

   • If the server is running, click Stop to stop the server or Restart to stop and then start the server.
   • If the server is stopped, click Start to start the server.
   • Click Close to return to the Introduction panel.
3. A message displays when the server successfully starts or stops.

If you need to perform server configuration maintenance, select the Start / Restart in configuration only mode check box. In this mode only the system administrator can bind to the server. All other connections are refused until the server is restarted with DB2 backends enabled (the Start / Restart in configuration only mode check box deselected). See Configuration only mode for additional information.

Note:

Configuration maintenance can be done while the server is running.

Using the command line:

Use the following command to start and stop the server:

Note:

The admin daemon must be running.

ibmdirctl [-h <hostname>] [-D <adminDN>] [-w <password>] [-p <portnumber>] 
  start|stop|restart|status -- [ibmslapd options]

See ibmdirctl for additional information.

For Windows^(R) systems use the previous command or:

1. From the desktop, double-click the My Computer icon.
2. Double-click the Control Panel icon.
3. Double-click the Services icon.
4. To start the server select IBM Directory V5.1 and click Start.
5. To stop the server select IBM Directory V5.1 and click Stop.

Configuration only mode

The IBM Directory Server supports LDAP access to the server's configuration settings. An administrator can use LDAP protocol to query and update the configuration for the server. This feature enables remote administration. In order for this access to be more robust and reliable, the server does not depend on successful initialization of the database backends. It is possible to start the server in configuration only mode with only the cn=configuration suffix active. In other words, as long as the configuration backend is available, the server starts and accepts LDAP requests. Configuration only mode gives an administrator remote access to the server even when errors are encountered during startup.

The following features are supported in configuration only mode:

• Access to the configuration file and log files.
• Auditing
• Event notification
• Kerberos
• SASL
• SSL

The following features are not supported in configuration only mode:

• Access to the database
• Changelog
• Password policy
• Replication
• Schema changes
• Transactions

Minimum requirements for configuration only mode

• The configuration file must be in the correct LDIF format and the server must be able to locate and read the file.
• The server must be able to read and load the schema according to the configuration file.
• The server must be able to load the configuration plugin.

How to start in configuration only mode

• Any failure during server startup causes the server to start in configuration only mode.
• Check the Configuration only mode when starting the server through the Web Administration Tool.
• Specify -a or -A on server startup.

  ibmslapd -a
  

  or

  ibmdirctl -h <hostname> -D <adminDN> -w <password>-p <portnumber> 
    start -- -a
  

  Note:

  The -n or -N options prevent the server from starting, if the server is unable to start with the database backends (not in configuration only mode).

How to verify that the server is running in configuration only mode

• If the server has started in configuration only mode the || icon located between the stop and start icons is highlighted.
• Issue a search of the root dse for the attribute ibm-slapdisconfigurationmode. If set to true, the server is running in configuration only mode.

  ldapsearch -s base -b " " objectclass=* ibm-slapdisconfigurationmode
  

Setting server properties

This section discusses how to set up the various properties for your server.

Note:

While the Web Administration Tool is the preferred method, updates to the server configuration file can be made through LDAP. The LDAP modify requests can be generated by:

• A C-application using the C-client provided with the IBM Directory Server
• A Java application using JNDI
• Any other interface that generates a standard V3 LDAP.

Examples that are provided use the ldapmodify command line utility.

ldapmodify can be run either in interactive mode or with inputs specified in a file. For most examples in this guide, the file contents to be used with the ldapmodify command are supplied. The general form of the command to use with these files is:

ldapmodify -D <adminDN> --w <password> --i <filename>

To update the server configuration settings dynamically, you need to issue the following ldapexop commands. This command updates all configuration settings that are dynamic:

ldapexop -D cn=root -w root -op readconfig -scope entire

This command updates a single setting.

ldapexop -D cn=root -w root -op readconfig -scope single <entry DN>
          <attribute>

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically. See Command line utilities for more information about the ldapmodify and ldapexop commands.

This panel also has two modifiable required fields, Unsecure port (default value is 389) and Secure port (default value 636) that display the respective current port numbers. If you want to change the port settings, enter a number ranging from 1 through 65535.

You must restart the server for changes to take effect.

Notes:

1. Only the administrator is allowed to update the server configuration settings.

2. If you change the port setting for the server, you must also change the port settings for the server in the console. See Managing the console.

Setting Performance

Note:

For the latest tuning information, see the IBM Directory Version 5.1 Tuning Guide located on the IBM Directory Server Web site located at http://www.ibm.com/software/network/directory/library/.

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Performance tab.

1. Specify the Maximum number of database connections. This sets the number of DB2 connections used by the server. If your LDAP server receives a high volume of client requests or clients are receiving "connection refused" errors, you might see better results by increasing the setting the number of connections made to DB2 by the server. While there are no longer any limitations upon the number of connections you specify, each connection does consume resources. Consult the IBM Directory Server Version 5.1 Tuning Guide for the latest tuning recommendations for you system.
2. Select Cache ACL information to use the following ACL cache settings. This option must be selected in order for the other cache setting options on this panel to take effect.
3. Specify the Maximum number of elements in ACL cache. The default is 25,000.
4. Specify the Maximum number of elements in entry cache. The default is 25,000.
5. Specify the Maximum number of elements in search filter cache. The default is 25,000. The search filter cache consists of actual queries on the requested attribute filters and resulting entry identifiers that matched. On an update operation, all filter cache entries are invalidated.
6. Specify the Maximum number of elements from a single search added to search filter cache. If you select Elements, you must enter a number. The default is 100. Otherwise, select Unlimited. Search entries that match more entries that the number specified here are not added to the search filter cache.
7. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
8. If you are setting the number of database connections, you must restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
changetype: modify
replace: ibm-slapdDbConnections
ibm-slapdDbConnections:  15
 
dn: cn=Front End, cn=Configuration
changetype: modify
replace: ibm-slapdACLCache
ibm-slapdACLCache: TRUE
-
replace: ibm-slapdACLCacheSize
ibm-slapdACLCacheSize: 25000
-
replace: ibm-slapdEntryCacheSize
ibm-slapdEntryCacheSize: 25000
-
replace: ibm-slapdFilterCacheSize
ibm-slapdFilterCacheSize: 25000
-
replace: ibm-slapdFilterCacheBypassLimit
ibm-slapdFilterCacheBypassLimit: 100
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Setting Searches

You can set search parameters to control users' search capabilities, such as paged and sorted searching.

Paged results allow you to manage the amount of data returned from a search request. You can request a subset of entries (a page) instead of receiving all the results at once. Subsequent search requests display the next page of results until the operation is canceled or the last result is returned. Sorted search allows a client to receive search results sorted by a list of criteria, where each criteria represents a sort key. This moves the responsibility of sorting from the client application to the server, where it might be done more efficiently.

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Search settings tab.

1. Set the Search size limit. Click either the Entries or the Unlimited radio button. If you select Entries, you need to specify in the field the maximum number of entries a search returns. If more entries fit the search criteria, they are not returned. This limit does not apply to the administrator.
2. Set the Search time limit. Click either the Seconds or the Unlimited radio button. If you select Entries, you need to specify in the field the maximum amount of time the server spends processing the request. This limit does not apply to the administrator.
3. To restrict search sorting capabilities to administrators, select the Only allow administrators to sort searches checkbox.
4. To restrict search paging capabilities to administrators, select the Only allow administrators to page searches checkbox.
5. To restrict ACL access to administrators and owners, select the Only allow administrators and owners to see ACLs on entries checkbox
6. Specify the number of entries to display per page of paged search results. This value determines the maximum number of entries allowed per page. If the number of entries per page of paged searches exceeds the search size limit, an error occurs.
7. Specify in seconds the time to wait (idle time out) for paged searches. Paged searches require an open connection between the LDAP server and the DB2 database where the LDAP data is stored. The idle time out administrative limit is designed to age out DB2 database connections held open for paged results search requests.
8. Specify the maximum number of concurrent paged searches allowed by the server at any given time.
9. Specify the maximum number of attributes used for sorting in sorted searches.
10. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

See Extended controls for search for additional information about searches.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Configuration
changetype: modify
replace: ibm-slapdTimeLimit
ibm-slapdTimeLimit:  900
-
replace: ibm-slapdSizeLimit
ibm-slapdSizeLimit:  500
 
dn: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
changetype: modify
replace: ibm-slapdPagedResAllowNonAdmin
ibm-slapdPagedResAllowNonAdmin: TRUE
-
replace: ibm-slapdPagedResLmt
ibm-slapdPagedResLmt: 3
-
replace: ibm-slapdPageSizeLmt
ibm-slapdPageSizeLmt: 201
-
replace: ibm-slapdSortKeyLimit
ibm-slapdSortKeyLimit: 3
-
replace: 
ibm-slapdSortSrchAllowNonAdmin: TRUE
 
dn: cn=Front End, cn=Configuration
changetype: modify
replace: ibm-slapdIdleTimeOut
ibm-slapdIdleTimeOut:  300 
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

See ldapsearch for information on how to perform searches using the command line.

Extended controls for search

The search function searches for a filter match on only the first 240 bytes of an attribute if indexing is enabled for that attribute. Additionally, if sort is specified on a search request, the server sorts the entries found by the search using only the first 240 bytes. Any end user or client application needs to take into consideration that a match for a search filter that exists in a value after the first 240 bytes might not be returned to the client depending on whether indexing is enabled for that table.

Note:

This restriction is specific to the IBM Directory Server. IBM LDAP servers on other platforms, including z/OS^(TM) and OS/400^(R) might have different restrictions. Consult the documentation for each platform to determine restrictions.

The administrator can tell if indexing has been enabled for an attribute by looking at the attribute definition in the Web Administration tool, or by looking at the attribute definition returned by a search of cn=schema. When viewing an attribute definition in the Web Administration tool, the IBM attributes fields includes one of the following index keywords: APPROX, EQUALITY, ORDERING, or SUBSTR. If the ldapsearch utility is used, the ibmattributetypes value contains the same keywords. For example, the 'cn' attribute has all indexes defined:

attributetypes=( 2.5.4.3 NAME ( 'cn' 'commonName' ) DESC 'This is the X.500 
                commonName attribute, which contains a name of an object.  
                If the object corresponds to a person, it is typically the 
                persons full name.' SUP 2.5.4.41 EQUALITY 2.5.13.2 
                ORDERING 2.5.13.3 SUBSTR 2.5.13.4 )
ibmattributetypes=( 2.5.4.3 DBNAME ( 'cn' 'cn' ) ACCESS-CLASS NORMAL LENGTH 
                   256 EQUALITY ORDERING SUBSTR APPROX )

Sorted search control

Sorted Search Results provides sort capabilities for LDAP clients that have limited or no sort functionality. Sorted Search Results allows an LDAP client to receive search results sorted based on a list of criteria, where each criteria represents a sort key. The sort criteria includes attribute types, matching rules, and descending order. The server uses this criteria to sort search results before returning them. This moves the responsibility of sorting from the client application to the server, where it might be done much more efficiently. For example, a client application might want to sort the list of employees at their Grand Cayman site by surname, common name, and telephone number. Instead of building the search list twice so it can be sorted (once at the server and then again at the client after all the results are returned), the search list is built only once, and then sorted, before returning the results to the client application.

The server sorts search entries based on attributes and by default allows a maximum of three sort keys (attribute names) per search operation. To change the value of this administrative limit, change the following line, ibm-slapdSortKeyLimit: 3, in the ibmslapd.conf file. See Setting Searches for information on how to do this. If the line does not exist, add it to set the new maximum (if the line does not exist, the server is using the default value). Additionally, because sorting search results before returning them uses more server resources than simply returning them, by default only requests from users binding with Administrator authority are honored by the server. If you would like the server to honor requests from all others, including those binding anonymously, you can configure the server to do so. To honor sorted search requests submitted using non-Administrator bind, change the following line, ibm-slapdSortSrchAllowNonAdmin: FALSE, in the ibmslapd.conf file. See Setting Searches. If the line does not exist, add it with a value of TRUE to allow non-Administrator bind. SeeAdding search attributes example .

The LDAP server returns all referrals to the client at the end of a search request, the same as is done today. It is up to the application using the client services to decide whether to set the criticality of the sorted search request, and to handle a lack of support of those controls on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports the sorted search control. Multiple lists could be returned to the client application, some not sorted. It is the client application's decision as to how to best present this information to the end user. Possible solutions include: combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly sorted list, otherwise when chasing referrals with sorted search controls specified, unpredictable results might occur.

It is important to note when taking advantage of the server sorted search results that:

• The server takes advantage of the underlying DB2 database to perform sorting of search results. This means that there might be different sorted search results based on the data code page for the database (especially if your database code page is UTF-8).
• Matching rules specified for a sort key attribute are ignored by the server. At this time, matching rules are not supported by the server.
• There is no support for multi-server sorting (referrals). The server cannot guarantee that referred servers support sorted search results.

More information about the server side sorted search control can be found in RFC 2891. The control OID for sorted search results is 1.2.840.113556.1.4.473, and is included in the RootDSE information as a supported control.

Simple paged results

Simple Paged Results provides paging capabilities for LDAP clients that want to receive just a subset of search results (page) instead of the entire list. The next page of entries is returned to the client application for each subsequent paged results search request submitted by the client until the operation is canceled or the last result is returned. The server ignores a simple paged results request if the page size is greater than or equal to the sizeLimit value for the server because the request can be satisfied in a single operation.

Because paging of search results holds server resources throughout the life of the simple paged results request, there are several new administrative limits employed to ensure that server resources cannot be abused, or misused, through the use of simple paged results search requests.

ibm-slapdPagedResAllowNonAdmin

By default only requests from users binding with Administrator authority is honored by the server. If you would like the server to honor requests from all others, including those binding anonymously, you can configure the server to do so. To honor simple paged results search requests submitted using non-Administrator bind, change the following line, ibm-slapdPagedResAllowNonAdmin: FALSE, in the ibmslapd.conf file. See Setting Searches. If the line does not exist, add it with a value of TRUE to allow non-Administrator bind. SeeAdding search attributes example .

ibm-slapdPagedResLmt

By default, the server allows a maximum of three outstanding simple paged results operations at any given time. To ensure the fastest response for subsequent simple paged results request, the server holds a database connection open throughout the life of the search request until the user cancels the simple paged results request, or the last result is returned to the client application. This administrative limit is designed to ensure that other operations being handled by the server are not denied service because all database connections are in use by outstanding simple paged results search requests. It is recommended that you set the ibm-slapdPagedResLmt value lower that the maximum number of database connections for your server. To change the value of this administrative limit, change the following line, ibm-slapdPagedResLmt: 3, in the ibmslapd.conf file. See Setting Searches. If the line does not exist add it to set the new maximum (if the line does not exist, the server is using the default value). SeeAdding search attributes example .

ibm-slapdPagedSizeLmt

By default, the server returns a maximum of 50 search results for a single page. If you would like to set a different page size maximum, you can change the following line, ibm-slapdPagedSizeLmt: 50, in the ibmslapd.conf file. See Setting Searches. If the line does not exist, add it with the value of the new maximum page size. SeeAdding search attributes example .

ibm-slapdIdleTimeOut

The idle time out administrative limit is designed to age out DB2 database connections held open for simple paged results search requests. The default idle time for simple paged results request is 500 seconds. For example, if a client application were to pause for 510 seconds between pages, the server would age out the request in order to free the database connection for use by other server operations. The server returns the appropriate error to the client application for the next simple paged results request submitted, at which point the client application needs to restart the simple paged results request. The idle timer for each simple paged results request is restarted after every page returned to the client application. The server checks for aged out simple paged results request every 5 seconds, so if you set the value of ibm-slapdIdleTimeOut value lower than 5 seconds, you still have to wait 5 seconds for the simple paged results requests to be aged out. To change the value of this administrative limit, change the following line, ibm-slapdIdleTimeOut: 300, in the ibmslapd.conf file. See Setting Searches. If the line does not exist add it to set the new maximum (if the line does not exist, the server is using the default value). SeeAdding search attributes example .

The LDAP server returns all referrals to the client at the end of a search request, the same as a search without any controls. That means that if the server has 10 pages of results returned, all the referrals are returned on the 10th page, not at the end of each page. When chasing referrals, the client application needs to send in an initial paged results request, with the cookie set to null, to each of the referral servers. It is up to the application using the client services to decide whether or not to set the criticality as to the support of paged results, and to handle a lack of support of this control on referral servers as appropriate based on the application. Additionally, the LDAP server does not ensure that the referral server supports paged results controls. Multiple lists could be returned to the client application, some not paged. It is at the client application's decision as to how to best present this information to the end user. Possible solutions include: combine all referral results before presenting to the end user; show multiple lists and the corresponding referral server host name; take no extra steps and show all results to the end user as they are returned from the server. The client application must turn off referrals to get one truly paged list, otherwise when chasing referrals with the paged results search control specified, unpredictable results may occur.

More information about the server side simple paged results control can be found in RFC 2686. The control OID for simple paged results is 1.2.840.113556.1.4.319, and is included in the RootDSE information as a supported control.

Adding search attributes example

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration
changetype: add
add: ibm-slapdSortSrchAllowNonAdmin
ibm-slapdSortSrchAllowNonAdmin: TRUE
-
add: ibm-slapdSortKeyLimit
ibm-slapdSortKeyLimit: 3
-
add: ibm-slapdPagedResAllowNonAdmin
ibm-slapdPagedResAllowNonAdmin: TRUE
-
add: ibm-slapdPagedResLmt
ibm-slapdPagedResLmt: 3
-
add: ibm-slapdPagedSizeLmt
ibm-slapdPagedSizeLmt: 50
-
add: ibm-slapdIdleTimeOut
ibm-slapdIdleTimeOut: 300
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

Transaction Support

Transaction processing enables an application to group a set of entry updates together in one operation. Normally each individual LDAP operation is treated as a separate transaction with the database. Grouping operations together is useful when one operation is dependent on another operation because if one of the operations fails, the entire transaction fails. Transaction settings determine the limits on the transaction activity allowed on the server.

Enabling transaction support

To enable transaction support:

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Transactions tab.

1. Select the Enable transaction processing check box to enable transaction processing. If Enable transaction processing is disabled, all other options on this panel, such as Maximum number of operations per transaction and Pending time limit, are ignored by the server.
2. Set the Maximum number of transactions. Click either the Transactions or the Unlimited radio button. If you select Transactions, you need to specify in the field the maximum number of transactions. The maximum number of transactions is 2,147,483,647. The default setting is 20 transactions.
3. Set the Maximum number of operations per transaction. Click either the Operations or the Unlimited radio button. If you select Operations, you need to specify in the field the maximum number of operations allowed for each transaction. The maximum number of operations is 2,147,483,647. The smaller the number, the better the performance. The default is 5 operations.
4. Set the Pending time limit. This selection sets the maximum timeout value of a pending transaction in seconds. Click either the Seconds or the Unlimited radio button. If you select Seconds, you net to specify in the field the maximum number of seconds allowed for each transaction. The maximum number of seconds is 2,147,483,647. Transactions left uncompleted for longer than this time are cancelled (rolled back). The default is 300 seconds.
5. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
6. If you have enabled transaction support, you must restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Transaction,cn=Configuration
changetype: modify
replace: ibm-slapdTransactionEnable
ibm-slapdTransactionEnable: TRUE 
-
replace: ibm-slapdMaxNumOfTransactions
ibm-slapdMaxNumOfTransactions: 20
-
replace: ibm-slapdMaxOpPerTransaction
ibm-slapdMaxOpPerTransaction: 5 
-
replace: ibm-slapdMaxTimeLimitOfTransactions
ibm-slapdMaxTimeLimitOfTransactions: 300
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Disabling transaction support

To disable transaction processing:

Using Web Administration:

1. Deselect the Enable transaction processing check box to enable transaction processing.
2. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
3. You must restart the server for the changes to take effect.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Transaction,cn=Configuration
changetype: modify
replace: ibm-slapdTransactionEnable
ibm-slapdTransactionEnable: False 
 

You must restart the server for the changes to take effect.

See the IBM Directory Server Version 5.1 C-Client SDK Programming Reference for more information about transaction support.

Event notification

The event notification function allows a server to notify a registered client that an entry in the directory tree has been changed, added or deleted. This notification is in the form of an unsolicited message.

When an event occurs, the server sends a message to the client as an LDAP v3 unsolicited notification. The messageID is 0 and the message is in the form of an extended operation response. The responseName field is set to the registration OID. The response field contains the unique registration ID and a timestamp for when the event occurred. The time field is in UTC time format.

Note:

When a transaction occurs, the event notifications for the transaction steps cannot be sent until the entire transaction is completed.

Enabling event notification

To enable event notification:

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Event notification tab.

1. Select the Enable event notification check box to enable event notification. If Enable event notification is disabled, the server ignores all other options on this panel.
2. Set the Maximum registrations per connection. Click either the Registrations or the Unlimited radio button. If you select Registrations, you need to specify in the field the maximum number of registrations allowed for each connection. The maximum number of transactions is 2,147,483,647. The default setting is 100 registrations.
3. Set the Maximum registrations total. This selection sets how many registrations the server can have at any one time. Click either the Registrations or the Unlimited radio button. If you select Registrations, you need to specify in the field the maximum number of registrations allowed for each connection. The maximum number of transactions is 2,147,483,647. The default number of registrations is Unlimited.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
5. If you have enabled event notification, you must restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Event Notification,cn=Configuration
changetype: modify
replace: ibm-slapdEnableEventNotification
ibm-slapdEnableEventNotification:  TRUE
-
replace: ibm-slapdMaxEventsPerConnection
ibm-slapdMaxEventsPerConnection:  100
-
replace: ibm-slapdMaxEventsTotal
ibm-slapdMaxEventsTotal:  0

If you have enabled event notification, you must restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Disabling event notification

To disable event notification:

Using Web Administration:

1. Deselect the Enable event notification check box to enable transaction processing.
2. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
3. You must restart the server for the changes to take effect.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=Event Notification,cn=Configuration
changetype: modify
replace: ibm-slapdEnableEventNotification
ibm-slapdEnableEventNotification:  FALSE
 

You must restart the server for the changes to take effect.

See the IBM Directory Server Version 5.1 C-Client SDK Programming Reference for more information about event notification.

Understanding suffixes

A 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 of every other entry within that directory hierarchy. A directory server can have multiple 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 not match any suffix configured for the local database, the query is referred to the LDAP server that is identified by the default referral. If no LDAP default referral is specified, an Object does not exist result is returned.

Creating or adding suffixes

To create or add a suffix use one of the following methods.

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Suffixes tab.

1. Enter the Suffix DN, for example, c=Italy. The maximum is 1000 characters for a suffix.
2. Click Add.
3. Repeat this process for as many suffixes as you want to add.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

DN: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
add: ibm-slapdSuffix
ibm-slapdSuffix: <suffixname>
ibm-slapdSuffix: <suffix2>
ibm-slapdSuffix: <suffix3>

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope single "cn=Directory,
    cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" ibm-slapdSuffix

Removing a suffix

To remove a suffix use one of the following methods:

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Suffixes tab.

1. From the Current suffix DNs section, select the suffixes you want to remove.
2. Click Remove.
3. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

DN: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
delete: ibm-slapdSuffix
ibm-slapdSuffix: <suffixname>
ibm-slapdSuffix: <suffix2>
ibm-slapdSuffix: <suffix3>

You must restart the server for the change to take effect.

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope single "cn=Directory,
    cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" ibm-slapdSuffix

Note:

You can also use the configuration utilities, ldapcfg, ldapucfg, and ldapxcfg to add and remove suffixes. See the IBM Directory Server Version 5.1 Installation and Configuration Guide for more information about these utilities.

Using referrals

Referrals provide a way for servers to refer clients to additional directory servers. A referral specifies the URL of an alternate LDAP server. This alternate server handles any requests for objects that are not found within any of the subtrees of the current LDAP server. With referrals you can:

• Distribute namespace information among multiple servers
• Provide knowledge of where data resides within a set of interrelated servers
• Route client requests to the appropriate server

Some of the advantages of using referrals are the ability to:

• Distribute processing overhead, providing primitive load balancing
• Distribute administration of data along organizational boundaries
• Provide potential for widespread interconnection, beyond an organization's own boundaries

Note:

On the Linux, Solaris, and HP-UX platforms, if a client hangs while chasing referrals, ensure that the environment variable LDAP_LOCK_REC has been set in your system environment. No specific value is required.

set LDAP_LOCK_REC=anyvalue

Using Web Administration:

Using the Web Administration utility is the recommended method to create and remove referrals.

Creating referrals

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Referrals tab.

1. Enter a referral URL beginning with the initial value ldap://. The maximum length is 32700 characters.
2. Click Add.
3. Repeat this process for as many referrals as you want to add.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel and return to the Introduction panel without making any changes.

You must restart the server for the changes to take effect.

Removing referrals

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Referrals tab.

1. From the Current referrals section, select the referral you want to remove.
2. Click Remove.
3. A confirmation panel is displayed. Click OK to remove the referral or click Cancel to return to the previous panel without making any changes.
4. Repeat this process for as many referrals as you want to remove.
5. When you are finished, click OK to apply your changes or click Cancel to exit this panel and return to the Introduction panel without making any changes.

You must restart the server for the changes to take effect.

Referrals

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

Using the referral object class and the ref attribute

The referral object class and the ref attribute are used to facilitate distributed name resolution or to search across multiple servers. The ref attribute appears in an entry named in the referencing server. The value of the ref attribute points to an entry maintained in the referenced server.

Creating entries

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

Figure 1. Example of using the referral attribute

In the example, Server A holds references to two entries: o=ABC, c=US and o=XYZ, c=US. For the o=ABC, c=US entry, Server A holds a reference to Server B and 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 hierarchy based on the subtrees they manage. Then, provide "forward" referrals from servers that hold higher (closer to the root of the hierarchy) information and set the default referral to point back to its parent server.

Associating servers with referrals

To associate servers through referrals:

• Use referral objects to point to other servers for subordinate references.
• 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 specifying the -M option.

Pointing to other servers

Use 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 consist of:

dn:

Specifies the distinguished name. It is the portion of the namespace served by the referenced server.

objectclass:

Specifies the value of the objectclass "referral".

ref:

Specifies the LDAP Web address of the server. This Web address consists of the ldap:// identifier, the hostname:port, and a DN. The identifier can be either 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 of the referral object. It is highly recommended that the DN specified in the value 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 by the referencing server.

dn:           o=IBM,c=US
objectclass:  referral
ref:          ldap://9.130.25.51:389/o=IBM,c=US

Defining the default referral

Define a default referral to reference a directory on another server. The default referral can be used to point to:

• The immediate parent of this server (in a hierarchy)
• A "more knowledgeable" server, such as the uppermost server in the hierarchy
• 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 includes only the ldap:// identifier and the hostname:port.

# referral  
dn: cn=Referral, cn=Configuration
objectclass: top
objectclass: ibm-slapdReferral
cn: Referral
ibm-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>

Deleting default referrals

To delete a single default referral, for example, austin.ibm.com:389, issue the command:

ldapmodify -D <adminDN> -w <adminPW> -f <filename>

where <filename> contains:

dn: cn=referral, cn= configuration
changetype: modify
delete: ibm-slapdReferral
ibm-slapdReferral: ldap://referral.austin.ibm.com:398
 

To delete all default referrals:

ldapdelete -D <adminDN> -w <adminPW> "cn=referral,cn=configuration"

Binding with a distributed namespace

When performing searches, the same DN that was used to bind or log in to the original server is used to bind to the referred-to server, unless the IBM Directory application is designed to modify the bind DN and credentials. The correct access must be set up for the same DN to be able to bind to both servers for chasing the referrals. See Logging on to the Web Administration Tool for additional information.

An example of distributing the namespace through referrals

Following are the steps involved in distributing the namespace using referrals.

1. Plan your namespace hierarchy.

   country - US
   company - IBM, Lotus
   organizationalUnit - IBM Austin, IBM Endicott, IBM Raleigh, IBM HQ
   

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

   Figure 2. Setting up the servers
   
   
   

   Server descriptions:

   Server A

   A server used to locate other servers in the U.S. With no other knowledge, clients can come here first to locate information for anyone in the U.S.

   Server B

   A hub for all data pertaining to IBM in the U.S. Holds all HQ information directly. Holds all knowledge (referrals) of where other IBM data resides.

   Server C

   Holds all IBM Austin information.

   Server D

   Holds all IBM Endicott information.

   Server E

   Holds all Lotus^(R) information.

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

   Figure 3. Server A database (LDIF input)
   
   
   

   Servers can also define a default referral, which is used to point to a "more knowledgeable" server for anything that is not underneath them in the namespace.

   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 objects in the database as well as the default referrals that are used for superior references.

Figure 4. Referral example summary

Securing the directory

This section describes the steps necessary for keeping the data in your directory secure.

Setting Secure Sockets Layer (SSL)

The IBM Directory Server has the ability to protect LDAP access by encrypting data with Secure Sockets Layer (SSL) security. When using SSL to secure LDAP communications with the IBM Directory, both server authentication and client authentication are supported. To use SSL you must have GSKit installed on your system. See Secure Sockets Layer and Using gsk6ikm for more information.

Configuring SSL settings

Expand the Manage security properties category in the navigation area of the Web Administration Tool, select the SSL settings tab.

1. Enable the type of SSL connections, select one of the following radio buttons:

   SSL Off

   Clients are permitted to conduct only unsecure communications.

   SSL On

   Clients are permitted to conduct either secure or unsecure communications.

   SSL Only

   Clients are not permitted to conduct unsecured communications. This is the most secure way to configure your server.

2. Select the authentication method.

   Note:

   You must distribute the server certificate to each client. For server and client authentication you also must add the certificate for each client to the server's key database.

   Select the radio button for either:

   Server authentication

   For server authentication the IBM Directory Server supplies the client with the IBM Directory Server's X.509 certificate during the initial SSL handshake. If the client validates the server's certificate, then a secure, encrypted communication channel is established between the IBM Directory Server and the client application.

   For server authentication to work, the IBM Directory Server must have a private key and associated server certificate in the server's key database file.

   Server and client authentication

   This type of authentication provides for two-way authentication between the LDAP client and the LDAP server. With client authentication, the LDAP client must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP client to the IBM Directory Server. See Client authentication.

3. Specify the secure port number to use. The default port is 636.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.
5. You must stop and restart both the IBM Directory Server and the administration daemon for the changes to take effect.
   1. Stop the server.
   2. Stop the administration daemon.
      • For Unix-based systems issue the commands:

        PS -ef | grep ibmdiradm
        kill -p <pid obtained by previous command>
        

      • For Windows-based systems, use Control panel ->Services, select IBM Directory Admin Daemon, click Stop.
   3. Start the administration daemon.
      • For Unix-based systems issue the command:

        ibmdiradm
         
        

      • For Windows-based systems, use Control panel ->Services, select IBM Directory Admin Daemon, click Start.
   4. Start the server.

Using the command line:

To use the command line to configure SSL communications, issue the command:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslAuth
ibm-slapdSslAuth: serverAuth | serverClientAuth
-
replace: ibm-slapdSecurity
ibm-slapdSecurity: none | SSL | SSlOnly
 

You must restart the server and the administration daemon for the changes to take effect.

Configuring for SSL certificate revocation verification

If you have selected to use server and client authentication in your SSL settings, you might want to configure your server to check for revoked or expired certificates.

When a client sends an authenticated request to a server, the server reads the certificate and sends a query to an LDAP server with a list that contains revoked certificates. If the client certificate is not found in the list, communications between the client and server are allowed over SSL. If the certificate is found, communications are not allowed.

To configure SSL certificate revocation verification, expand the Manage security properties category in the navigation area of the Web Administration Tool, select the Certificate revocation tab.

1. Enter the name of the server that contains certificates that have been revoked . This server is designated by the certificate granting authority (CA) that you use, for example Verisign. The format of the host name is hostName.domainName, for example, myserver.myorg.com.
2. Enter the port used to communicate with the server, for example 389.
3. Enter the DN used to bind to the verifying server, for example cn=root. This is optional if the verifying server allows anonymous searches for certificate revocation lists (CRLs).
4. Enter the password associated with the bind DN. This is required if you specified a DN.
5. Type the bind password again to confirm that there are no typographical errors.
6. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Note:

Expired certificates are not included in the list because the expiration date is contained in the certificate itself.

Using the command line:

To use the command line to configure for SSL certificate revocation verification, issue the command:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=CRL,cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdCrlHost
ibm-slapdCrlHost: <newhostname>
-
replace: ibm-slapdCrlPassword
ibm-slapdCrlPassword: <password>
-
replace: ibm-slapdCrlPort
ibm-slapdCrlPort: <portnumber>
-
replace: ibm-slapdCrlUser
ibm-slapdCrlUser: <username>
 

You must restart the server and the administration daemon for the changes to take effect.

Setting the SSL key database

Expand the Manage security properties category in the navigation area of the Web Administration Tool, select the SSL key database tab.

1. Specify the Key label. This administrator-defined key label indicates what part of the key database to use.
2. Specify the Key database path and file name. This is the fully-qualified file specification of the key database file. If a password stash file is defined, it is assumed to have the same file specification, with an extension of .sth.
3. Specify the Key password. If a password stash file is not being used, the password for the key database file must be specified here. Then specify the password again in the Confirm password field.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Note:

In order for the server to use this file, it must be readable by the userid ldap. See File permissions.

Using the command line:

To use the command line to set the SSL key database, issue the command:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSSLKeyDatabase
ibm-slapdSSLKeyDatabase: <databasename>
-
replace: ibm-slapdSSLKeyDatabasePW
ibm-slapdSSLKeyDatabasePW: <password>
-
replace: ibm-slapdSslKeyRingFile
ibm-slapdSslKeyRingFile: <filename>
-
replace: ibm-slapdSslKeyRingFilePW
ibm-slapdSslKeyRingFilePW: <password>
 

You must restart the server and the administration daemon for the changes to take effect.

Setting the SSL level of encryption

By default the SSL version of IBM Directory Server uses the following list of ciphers when performing cipher negotiation with the client (during the SSL handshake).

From the navigation area in the Web Administration tool, select SSL encryption.

1. Select the method of SSL encryption that you want to use based on the clients accessing the server. If you select multiple encryption methods, the highest level of encryption is used by default, however clients using the selected lower encryption levels still have access to the server.

   Note:

   The IBM Directory Server Version 5.1 now supports the Advanced Encryption Standard (AES) level of encryption. For information on AES, see the NIST Web page at http://csrc.nist.gov/encryption/aes/.

   
   

   Table 4.
   

   Encryption level	Attribute
   Triple DES encryption with a 168-bit key and a SHA-1 MAC	ibm-slapdSslCipherSpec: TripleDES-168
   DES encryption with a 56-bit key and a SHA-1 MAC	ibm-slapdSslCipherSpec: DES-56
   RC4 encryption with a 128-bit key and a SHA-1 MAC	ibm-slapdSslCipherSpec: RC4-128-SHA
   RC4 encryption with a 128-bit key and a MD5 MAC	ibm-slapdSslCipherSpec: RC4-128-MD5
   RC2 encryption with a 40-bit key and a MD5 MAC	ibm-slapdSslCipherSpec: RC2-40-MD5
   RC4 encryption with a 40-bit key and a MD5 MAC	ibm-slapdSslCipherSpec: RC4-40-MD5
   AES encryption	ibm-slapdSslCipherSpec: AES

   The selected ciphers are stored in the configuration file using the ibm-slapdsslCipherSpec keyword and the attribute defined from the preceding table. For example, to use only Triple DES, select Triple DES encryption with a 168-bit key and an SHA-1 MAC. The attribute ibm-slapdSslCipherSpec: TripleDES-168 is added to the ibmslapd.conf file. In this case, only clients that also support Triple DES are able to establish an SSL connection with the server.

2. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To use the command line to set the SSL level of encryption, in this example to AES, issue the command:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslCipherSpec
ibm-slapdSslCipherSpec: AES

See Table 4 for other encryption values. You must restart the server and the administration daemon for the changes to take effect.

Secure Sockets Layer

The IBM Directory Server has the ability to protect LDAP access by encrypting data with Secure Sockets Layer (SSL) security. When using SSL to secure LDAP communications with the IBM Directory, both server authentication and client authentication are supported.

With server authentication, the IBM Directory Server must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the IBM Directory Server to the client application (such as the Directory Management Tool or ldapsearch) or an application built from the application development package, for LDAP access over SSL.

For server authentication the IBM Directory Server supplies the client with the IBM Directory Server's X.509 certificate during the initial SSL handshake. If the client validates the server's certificate, then a secure, encrypted communication channel is established between the IBM Directory Server and the client application.

For server authentication to work, the IBM Directory Server must have a private key and associated server certificate in the server's key database file.

Client authentication provides for two-way authentication between the LDAP client and the LDAP server.

With client authentication, the LDAP client must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP client to the IBM Directory Server. See Client authentication.

To conduct commercial business on the Internet, you might use a widely known Certification Authority (CA), such as VeriSign, to get a high assurance server certificate.

Securing your server with SSL

The following high-level steps are required to enable SSL support for IBM Directory for server authentication. These steps assume you have already installed and configured the IBM Directory Server:

1. Install the IBM Directory GSKit package if it is not installed. See the IBM Directory Server Version 5.1 Installation and Configuration Guide for information on installing the GSKit package.
2. Generate the IBM Directory Server private key and server certificate using the gsk6ikm utility (installed with GSKit). The server's certificate can be signed by a commercial CA, such as VeriSign, or it can be self-signed with the gsk6ikm tool. The CA's public certificate (or the self-signed certificate) must also be distributed to the client application's key database file.
3. Store the server's key database file and associated password stash file on the server. The default path for the key database,...\ldap\etc directory, is a typical location.
4. Access the Web-based LDAP administrative interface to configure the LDAP server. See Configuring SSL settings for the procedures.

If you also want to have secure communications between a master IBM Directory Server and one or more replica servers, you must complete the following additional steps:

1. Configure the replica directory server.

   Note:

   Follow the steps shown above for the master, except perform them for each replica. When configuring a replica for SSL, the replica is like the master with respect to its role when using SSL. The master is an LDAP client (using SSL) when communicating with a replica.

2. Configure the master directory server:
   1. 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 is actually an LDAP client. If using self-signed certificates, you must extract all the self-signed certificates from each replica IBM Directory Server, and add them to the master's key database, and ensure they are marked as trusted-roots. Essentially, you are configuring the master as an SSL client of the replica server.
   2. Configure the master IBM Directory Server to be aware of the replica server. Be sure to set the replicaPort attribute to use the port which the replica IBM 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.

Setting Server authentication

For server authentication, you can modify the ibmslapd.conf file under the cn=SSL, cn=Configuration entry. To use the Web Administration Tool, see Configuring SSL settings.

To use the command line:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSSLAuth
ibm-slapdSSLAuth: serverAuth
 

You must restart the server and the administration daemon for the changes to take effect.

Server certificate from an external Certificate Authority (CA)

In order to provide a secure connection between IBM Directory and its clients, the server must have an X.509 certificate and a private key.

The steps required to generate a private key, obtain the required server certificate from an external CA, and prepare them for use by the IBM Directory are outlined in the following:

1. Logon as administrator or root.
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 gsk6ikm to create a new key database file. You can use any valid value for the key database file name that you want. Whatever file name you use, you need to provide it when configuring the LDAP server to use SSL. Providing a full path name is recommended. The gsk6ikm utility is used to generate a private-public key pair and a certificate request. SeeUsing gsk6ikm for additional information.

   Note:

   By default, the new KDB created by GSKit is not readable by the server. You must change the owner to ldap.

   chown ldap:ldap <mykeyring>.*
   

   See Kerberos service name change for a more detailed explanation.

4. If VeriSign is your external CA, obtain a certificate from VeriSign, as follows:
   1. Access the following VeriSign Web site: http://digitalid.verisign.com/server_ids.html
   2. Click on IBM internet connection servers.
   3. After reviewing the information at this site, click on Begin.
   4. Provide the required information and follow the steps required to request your server certificate. VeriSign is the primary Certification Authority supported for obtaining externally generated, high-assurance server certificates.
5. If you have another CA that you want to use, follow the directions for that CA to submit the contents of the certificate request file to them.

When you receive the resulting certificate from the 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 is used in the next step.
4. From the same directory, run gsk6ikm 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 database file. See Configuring SSL settings.
6. If you have more than one certificate in the key database file, the certificate you wish to use for IBM Directory must be the default.
7. Start the IBM Directory.

Note:

If you instruct gsk6ikm to save the password in a password stash file, it is not necessary to change or set the password in the ibmslapd.conf file.

Using a self-signed server certificate

If you are using the IBM Directory in an intranet environment, use gsk6ikm to create your own server certificates. You can also use gsk6ikm to test IBM Directory with SSL without purchasing a VeriSign high-assurance server 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:
   1. Change to the directory where you wish to create the key database file and where your private key and certificate is to be stored.
   2. Create a new key database file and the self-sign certificate request that is to be used as your CA certificate.
      • Use the largest key size available.
      • Use a secure server certificate, not a low-assurance certificate.
   3. Obtain the certificate request file. The certificate is put into the key database file automatically by the gsk6ikm tool.
2. If you are using an application created for the client, do the following on each client machine:
   1. Place the CA certificate request file in an accessible location on the client machine.
   2. Receive the CA certificate request file into the client's key database.
   3. Mark the received certificate as a trusted root.

See Using gsk6ikm for additional information.

Notes:

1. You must always receive the CA certificate into the server's key database file and mark it as a trusted root before receiving the server certificate into the server's key database file.

2. Whenever you use gsk6ikm to manage the IBM Directory Server's key database file, remember to change to the directory in which the key database file exists.

3. Each IBM Directory Server must have its own private key and certificate. Sharing the private key and certificate across multiple IBM Directory Servers increases security risks. By using different certificates and private keys for each server, security exposure is minimized if a key database file for one of the servers is compromised.

Setting up your LDAP client to access IBM Directory

The following steps are required to create a key database file for an LDAP client that 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 other sources, 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 (for example VeriSign, or the creator of a self-signed server certificate), imported into the client's key database file, and marked as trusted.

1. Copy the server's certificate file (cert.arm) to your client workstation.
2. Run gsk6ikm 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 the client for ease of management. For example, if the LDAP client runs on Fred's machine, you might choose to name the file FRED.KDB.
3. If adding a server's certificate to the existing client key database:
   1. Click Key database file and select Open.
   2. Enter the path and name of the existing key database file then click OK.
   3. Enter the password.
   4. Ensure signer certificates is chosen. Click Add.
   5. Enter the name and location of the server's certificate file.
   6. 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:
   1. Click Key database file and select New.
   2. Enter the name and location for the new Client Key DataBase file, then click OK.
   3. Enter the password.
   4. 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 gsk6ikm.

See Using gsk6ikm for additional information.

When the LDAP client creates a secure SSL connection with the server, it uses the server's self-signed certificate to verify that it is connecting to the proper server.

Repeat the preceding steps for each IBM Directory Server that the LDAP client needs to connect to in a secure fashion.

Migrate the key ring file to key database file

To migrate the old key ring file which was created from MKKF utility, do the following steps:

1. Start gsk6ikm.
2. Click Key database file of menu bar and select Open.
3. Enter the path and filename of your key ring file then click OK.
4. Enter the password of your key ring file. If the key ring file is created without a password, you must use the old MKKF to assign a password for it.
5. After the old Key ring file is opened, click Key database file and select Save ss.
6. Ensure key database type is set to CMS key database file. Fill out the name and location of the key database file, and then click OK.

Client authentication

Client authentication provides for two-way authentication between the LDAP client and the LDAP server.

With client authentication, the LDAP client must have a digital certificate (based on the X.509 standard). This digital certificate is used to authenticate the LDAP client to the IBM Directory Server.

The Simple Authentication and Security Layer (SASL) can be used to add authentication support to connection protocols. A protocol includes a command for identifying and authenticating a user to a server. It can optionally negotiate a security layer for subsequent protocol interactions.

After a server receives the authentication command or any client response, it may issue a challenge or indicate failure or completion. If a client receives a challenge it may issue a response or abort the exchange, depending on the profile of the protocol.

During the authentication protocol exchange, the SASL mechanism performs authentication, transmits an authorization identity (known as userid) from the client 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 processes the request in the following order:

1. The server parses the LDAP bind request and retrieves the following information:
   • The DN that the client is attempting to authenticate as.
   • The method of authentication used.
   • Any credentials, such as a password included in the request.
   • 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 SASL mechanism is not supported by the server, the server sends an error return code to the client and ends the bind process.
5. If the SASL mechanism is supported (=EXTERNAL) and the SSL authentication type is server and client authentication, the server verifies that the client's certificate is valid, issued by a known CA, and that none of the certificates on the client's certificate chain are invalid or revoked. If the client DN and password, as specified in the ldap_sasl_bind, are NULL, then the DN contained within the client's x.509v3 certificate is used as the authenticated identity on subsequent LDAP operations. Otherwise, the client is authenticated anonymously (if DN and password are NULL), or the client is authenticated based on the bind information provided by the client.
6. If the method of authentication is Simple, the server checks to see if the DN is an 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, the server assumes that the client is binding anonymously and returns a good result to the client. The DN and authentication method for the connection are left as NULL and LDAP_AUTH_NONE respectively.
8. If the client has not bound beforehand, and does not present a certificate during the bind operation, the connection is refused.

Setting client authentication

For client authentication, you can modify the ibmslapd.conf file under the cn=SSL, cn=Configuration entry. To use the Web Administration Tool, see Configuring SSL settings.

To use the command line:

ldapmodify -D <AdminDN> -w <Adminpassword> -i <filename>

where <filename> contains:

dn: cn=SSL,cn=Configuration
cn: SSL
changetype: modify
replace: ibm-slapdSSLAuth
ibm-slapdSSLAuth: serverClientAuth
 

You must restart the server and the administration daemon for the changes to take effect.

Using gsk6ikm

The following key-management program is provided with IBM's Global Security Kit (GSKit):

• gsk6ikm - A user-friendly GUI for managing key files, implemented as a Java applet.

Note:

On the AIX^(R) operating systems, if you are prompted to set JAVA_HOME, you can set it to either the system-installed Java or the Java version included with the IBM Directory Server. If you use the IBM Directory Server version, you also need to set the LIBPATH environment variable as follows:

  export LIBPATH=/usr/ldap/java/bin:/usr/ldap/java/bin/classic:$LIBPATH
 

Use gsk6ikm to create public-private key pairs and certificate requests, receive certificate requests into a key database file, and manage keys in a key database file.

The tasks you can perform with gsk6ikm include:

• Creating a key pair and requesting a certificate from a certificate authority
• Receiving a certificate into a key database file
• Managing keys and certificates
  • Changing a key database password
  • Showing information about a key
  • Deleting a key
  • Making a key the default key in the key database
  • Creating a key pair and certificate request for self-signing
  • Exporting a key
  • Importing a key into a key database
  • Designating a key as a trusted root
  • Removing trusted root key designation
  • Requesting a certificate for an existing key
• Migrating a keyring file to the key database format

Creating a key pair and requesting a certificate from a Certificate Authority

If your client application is connecting to an LDAP server that requires client and server authentication, then you need to create a public-private key pair and a certificate.

If your client application is connecting to an LDAP server that only requires server authentication, it is not necessary to create a public-private key pair and a certificate. It is sufficient to have a certificate in your client key database file that is marked as a trusted root. If the Certification Authority (CA) that issued the server's certificate is not already defined in your client key database, you need to request the CA's certificate from the CA, receive it into your key database, and mark it as trusted. See Designating a key as a trusted root.

Your client uses its private key to sign messages sent to servers. The server sends its public key to clients so that they can encrypt messages to the server, which the server decrypts with its private key.

To send its public key to a server, the client needs a certificate. The certificate contains the client's public key, the Distinguished Name associated with the client's certificate, the serial number of the certificate, and the expiration date of the certificate. A certificate is issued by a CA, which verifies the identity of the client.

The basic steps to create a certificate that is signed by a CA are:

1. Create a certificate request using gsk6ikm.
2. Submit the certificate request to the CA. This can be done using E-mail or an on-line submission from the CA's Web page.
3. Receive the response from the CA to an accessible location on the file system of your server.
4. Receive the certificate into your key database file.

Note:

If you are obtaining a signed client certificate from a CA that is not in the default list of trusted CAs, you need to obtain the CA's certificate, receive it into your key database and mark it as trusted. This must be done before receiving your signed client certificate into the key database file.

To create a public-private key pair and request a certificate:

1. Start gsk6ikm Java utility by typing:

   gsk6ikm
   

2. Select Key database file.
3. Select New (or Open if the key database already exists).
4. Specify key database file name and location. Type OK.

   Note:

   A key database is a file that the client or server uses to store one or more key pairs and certificates.

5. When prompted, supply password for the key database file. Click OK.
6. Select Create.
7. Select New certificate request.
8. Supply user-assigned label for key pair. The label identifies the key pair and certificate in the key database file.
9. If you are requesting a low-assurance client certificate, enter the common name. This must be unique and the full name of the user.
10. If you are requesting a high-assurance secure server certificate, then:
    • Enter the X.500 common name of the server. Usually this is the TCP/IP fully qualified host name, for example, www.ibm.com. For a VeriSign server certificate, it must be the fully qualified host name.
    • Enter the organization name. This is the name of your organization. For a VeriSign secure server certificate, if you already have an account with VeriSign, the name in this field must match the name on that account.
    • Enter the organizational unit name. This is an optional field.
    • Enter the locality/city where the server is located. This is an optional field.
    • Enter a three-character abbreviation of the state/province where the server is located.
    • Enter the postal code appropriate for the server's location.
    • Enter the two-character country code where the server is located.
11. Click OK.
12. A message identifying the name and location of the certificate request file is displayed. Click OK.
13. Send the certificate request to the CA.

    If this is a request for a VeriSign low assurance certificate or secure server certificate, you must E-mail the certificate request to VeriSign.

    You can mail the low assurance certificate request to VeriSign immediately. A secure server certificate request requires more documentation. To find out what VeriSign requires for a secure server certificate request, go to the following URL: http://www.verisign.com/ibm.

14. When you receive the certificate from the CA, use gsk6ikm to receive it into the key database where you stored the key pair. See Receiving a certificate into a key database.

Note:

Change the key database password frequently. If you specify an expiration date, you need to keep track of when you need to change the password. If the password expires before you change it, the key database is not usable until the password is changed.

Receiving a certificate into a key database

After receiving a response from your CA, you need to receive the certificate into a key database.

To receive a certificate into a key database:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file, click OK.
6. Select Create.
7. Select Personal certificates in the middle display window.
8. Click Receive.
9. Enter name and location of the certificate file that contains the signed certificate, as received from the CA. Click OK.

Changing a key database password

To change a key database password:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Key database file.
7. Select Change password.
8. Enter <New password>.
9. Confirm <New password>.
10. Select and set optional password expiration time.
11. Select Stash the password to a file? if you want the password to be encrypted and stored on disk.
12. Click OK.
13. A message is displayed with the file name and location of the stash password file. Click OK.

Note:

The password is important because it protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key.

Showing information about a key

To show information about a key, such as its name, size or whether it is a trusted root:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. To see information about keys designated as Personal certificates:
   • Select Personal certificates at the top of the Key database content window.
   • Select a certificate.
   • Click View/Edit to display information about the selected key.
   • Click OK to return to the list of Personal Certificates.
7. To see information about keys that are designated as Signer Certificates:
   • Select Signer certificates at the top of the Key database content window.
   • Select a certificate .
   • Click View/Edit to display information about the selected key.
   • Click OK to return to the list of Signer Certificates.

Deleting a Key

To delete a key:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select the type of key you want to delete at the top of the Key database content window (Personal certificates, Signer certificates, or Personal certificate requests).
7. Select a certificate.
8. Click Delete.
9. Click Yes to confirm.

Making a key the default key in the key ring

The default key must be the private key the server uses for its secure communications.

To make a key the default key in the key ring:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Personal certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click View/Edit.
9. Select the Set the certificates as the default box. Click OK.

Creating a key pair and certificate request for self-signing

By definition, a secure server must have a public-private key pair and a certificate.

The server uses its private key to sign messages to clients. The server sends its public key to clients so they can encrypt messages to the server, which the server decrypts with its private key.

The server needs a certificate to send its public key to clients. The certificate contains the server's public key, the Distinguished Name associated with the server's certificate, the serial number of the certificate, and the expiration date of the certificate. A certificate is issued by a CA, who verifies the identity of the server.

You can request one of the following certificates:

• A low assurance certificate from VeriSign, best for non-commercial purposes, such as a beta test of your secure environment
• A server certificate to do commercial business on the Internet from VeriSign or some other CA
• A self-signed server certificate if you plan to act as your own CA for a private Web network

For information about using a CA such as VeriSign to sign the server certificate, see Creating a key pair and requesting a certificate from a Certificate Authority.

The basic steps to creating a self-signed certificate are:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select New, or Open if the key database already exists.
4. Specify key database file name and location. Type OK.

   Note:

   A key database is a file that the client or server uses to store one or more key pairs and certificates.

5. When prompted, supply password for the key database file. Click OK.
6. Click New self-signed.
7. Supply the following:
   • User-assigned label for key pair. The label identifies the key pair and certificate in the key database file.
   • Select the desired certificate Version.
   • Select the desired Key Size.
   • Enter the X.500 common name of the server. Usually this is the TCP/IP fully qualified host name, for example, www.ibm.com.
   • Enter the organization name. This is the name of your organization.
   • Enter the organizational unit name. This is an optional field.
   • Enter the locality/city where the server is located. This is an optional field.
   • Enter a three-character abbreviation of the state/province where the server is located.
   • Enter the zip code appropriate for the server's location.
   • Enter the two-character country code where the server is located.
   • Enter the Validity Period for the certificate.
8. Click OK.

Exporting a key

If you need to transfer a key pair or certificate to another computer, you can export the key pair from its key database to a file. On the other computer, you can import the key pair into a key ring.

To export a key from a key database:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Personal certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click Export/Import.
9. For Action type, select Export key.
10. Select the Key file type:
    • PKCS12 file
    • CMS Key database file
    • Keyring file (as used by mkkf)
    • SSLight key database class
11. Specify a file name.
12. Specify location.
13. Click OK.
14. Enter the required password for the file. Click OK.

Importing a key

To import a key into a key ring:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Personal certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click Export/Import.
9. For Action type, select Import key.
10. Select the desired Key file type.
11. Enter the file name and location.
12. Click OK.
13. Enter the required password for the source file. Click OK.

Designating a key as a trusted root

A trusted root key is the public key and associated Distinguished Name of a CA. The following trusted roots are automatically defined in each new key database:

• Integrion Certification Authority Root
• IBM World Registry^(TM) Certification Authority
• Thawte Personal Premium CA
• Thawte Personal Freeemail CA
• Thawte Personal Basic CA
• Thawte Premium Server CA
• VeriSign Test CA Root Certificate
• RSA Secure Server Certification Authority
• VeriSign Class 1 Public Primary Certification Authority
• VeriSign Class 2 Public Primary Certification Authority
• VeriSign Class 3 Public Primary Certification Authority
• VeriSign Class 4 Public Primary Certification Authority

Note:

Each of these trusted roots are initially set to be trusted roots by default.

To designate a key as a trusted root:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Signer certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click View/Edit.
9. Check the Set the certificate as a trusted root box, and click OK.
10. Select Key database file and then select Close.

Removing a key as a trusted root

A trusted root key is the public key and associated Distinguished Name of a CA. The following trusted roots are automatically defined in each new key database:

• Integrion Certification Authority Root
• IBM World Registry Certification Authority
• Thawte Personal Premium CA
• Thawte Personal Freeemail CA
• Thawte Personal Basic CA
• Thawte Premium Server CA
• VeriSign Test CA Root Certificate
• RSA Secure Server Certification Authority
• VeriSign Class 1 Public Primary Certification Authority
• VeriSign Class 2 Public Primary Certification Authority
• VeriSign Class 3 Public Primary Certification Authority
• VeriSign Class 4 Public Primary Certification Authority

Note:

Each of these trusted roots are initially set to be trusted roots by default.

To remove the trusted root status of a key:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Signer certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click View/Edit.
9. Uncheck the Set the certificate as a trusted root box. Click OK.
10. Select Key database file and then select Close.

Requesting a certificate for an existing key

To create a certificate request for an existing key:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the key database file. Click OK.
6. Select Personal Certificates at the top of the Key database content window.
7. Select the desired certificate.
8. Click Export/Import.
9. For Action type, select Export key.
10. Select the desired Data type:
    • Base 64-encoded ASCII data
    • Binary DER data
    • SSLight Key Database Class
11. Enter the certificate file name and location.
12. Click OK.
13. Select Key database file and then select Close.

Send the certificate request to the CA.

If this is a request for a VeriSign low assurance certificate or secure server certificate, you must E-mail the certificate request to VeriSign.

You can mail the low assurance certificate request to VeriSign immediately. A secure server certificate request requires more documentation. To find out what VeriSign requires for a secure server certificate request, go to the following URL: http://www.verisign.com/ibm.

Migrating a keyring file to the key database format

The gsk6ikm program can be used to migrate an existing keyring file, as created with mkkf, to the format used by gsk6ikm.

To migrate a keyring file:

1. Type gsk6ikm to start the Java utility.
2. Select Key database file.
3. Select Open.
4. Specify key database file name and location. Type OK.
5. When prompted, supply password for the keyring file. Click OK.
6. Select Key database file.
7. Select Save as....
8. Select CMS key database file as the Key database type.
9. Specify a file name.
10. Specify location.
11. Click OK.

Setting password security

Password policy is a set of rules that controls how passwords are used and administered in the IBM Directory. These rules are made to ensure that users change their passwords periodically, and that the passwords meet the organization's syntactic password requirements. These rules also can restrict the reuse of old passwords and ensure that users are locked out after a defined number of failed attempts.

All users except the directory administrator are forced to comply with this password policy. The password for the administrator never expires and the account is never locked. The directory administrator has sufficient access control privileges to modify users' passwords and the password policy.

Setting password policy

Expand the Manage security properties category in the navigation area of the Web Administration Tool, select the Password policy tab.

1. Select the type of password encryption from the drop-down list:
   • None
   • imask
   • crypt
   • sha

   See Password encryption for additional information.

2. Select the Password policy enabled checkbox to enable password policy.

   Note:

   If Password policy is not enabled, none of the other functions on this or the other password panels are available until the checkbox is enabled. By default password policy is disabled.

3. Select the User can change password checkbox to specify whether the user can change the password.
4. Select the User must change password after reset checkbox to specify whether the user must change the password after logging on with a reset password.
5. Select the User must send password when changing checkbox to specify whether the user, after the initial log on, needs to specify the password again before being able to change the password.
6. Set the password expiration limit. Click the Password Never Expires radio button to specify that the password does not have to be changed at a specific time interval or click the Days radio button and specify the time interval, in days, when the password needs to be reset.
7. Specify whether the system issues a password expiration warning, before the password expires. If you click the Never warn radio button, the user is not warned before the previous password expires. The user cannot access the directory until the administrator has created a new password. If you click the Days before expiration radio button and specify a number of days (n), the user receives a warning prompt to change the password each time the user logs on, starting n days before the password expires. The user can still access the directory until the password expires.
8. Specify the number of times, if any, that the user can log on after the password has expired. This selection enables the user to access the directory with an expired password.
9. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=pwdpolicy
changetype: modify
replace: ibm-pwdpolicy
ibm-pwdpolicy: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace:pwdallowuserchange
pwdallowuserchange: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace:pwdmustchange
pwdmustchange: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace:pwdmaxage
pwdmaxage: 5
-
replace:pwdexpirewarning
pwdexpirewarning: 7
-
replace:pwdgraceloginlimit
pwdgraceloginlimit: 2
 

You must restart the server for the changes to take effect.

Setting password lockout

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Password lockout tab.

Note:

If password policy is not enabled on the server, the functions on this panel do not take effect.

1. Specify the number of seconds, minutes, hours or days that must expire before a password can be changed.
2. Specify whether incorrect logins lockout the password.
   • Select the Passwords are never locked out radio button if you want to allow unlimited log in attempts. This selection disables the password lockout function.
   • Select the Attempts radio button and specify the number of log in attempts that are allowed before locking out the password. This selection enables the password lockout function.
3. Specify the duration of the lockout. Select the Lockouts never expires radio button to specify that the system administrator must reset the password or select the Seconds radio button and specify the number of seconds before the lockout expires and log in attempts can resume.
4. Specify the expiration time for an incorrect login. Click the Incorrect logins only cleared with correct password radio button to specify that incorrect logins are cleared only by a successful login or click the Seconds radio button and specify the number of seconds before an unsuccessful login attempt is cleared from memory.

   Note:

   This option works only if the password is not locked out.

5. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=pwdpolicy
changetype: modify
replace: pwdlockout
pwdlockout: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace:pwdmaxfailure
pwdmaxfailure: 3
-
replace:pwdlockoutduration
pwdlockoutduration: 15
-
replace:pwdfailurecountinterval
pwdfailurecountinterval: 30
-
replace:pwdexpirewarning
pwdexpirewarning: 7
-
replace:pwdgraceloginlimit
pwdgraceloginlimit: 2
 

Setting password validation

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Password validation tab.

Note:

If password policy is not enabled on the server, the functions on this panel do not take effect.

1. Set the number of passwords that must be used before a password can be reused. Enter a number from 0 to 30. If you enter zero, a password may be reused without restriction.
2. From the drop down box, select whether the password is checked for the syntax defined in the following entry fields. You can select:

   Do not check syntax

   No syntax checking is performed.

   Check syntax (except encrypted)

   The syntax checking is performed on all unencrypted passwords.

   Check syntax

   The syntax checking is performed on all passwords.

Setting syntax requirements

1. Specify a number value to set the minimum length of the password. If the value is set to zero, no syntax checking is performed.
   • Specify a number value to set the minimum number of alphabetic characters required for the password.
   • Specify a number value to set the minimum number of numeric and special characters required for the password.

   Note:

   The sum of the minimum number of alphabetic, and numeric and special characters must be equal to or less than the number specified as the minimum length of the password.

2. Specify the maximum number of characters that can be repeated in the password. This option limits the number of times a specific character can appear in the password. If the value is set to zero, the number of repeated characters is not checked.
3. Specify the minimum number of characters that must be different from the previous password and the number of previous passwords specified in the Minimum number of passwords before reuse field. If the value is set to zero, the number of different characters is not checked.
4. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To perform the same operations using the command line, issue the following command:

ldapmodify -D <AdminDN> -w<Adminpassword> -i<filename>

where <filename> contains:

dn: cn=pwdpolicy
changetype: modify
replace: pwdinhistory
pwdinhistory: 8
-
replace:pwdchecksyntax
pwdchecksyntax: 0|1|2
# 0=No syntax check
#1=Check syntax (except encrypted)
#2=Check syntax on all-
replace:pwdminlength
pwdminlength: 6
-
replace:passwordminalphachars
passwordminalphachars: 3
-
replace:passwordminotherchars
passwordminotherchars: 3
-
replace:passwordmaxrepeatedchars
passwordmaxrepeatedchars: 2
-
replace:passwordmindiffchars
passwordmindiffchars: 4
 

Password encryption

IBM Directory allows you to prevent unauthorized access to user passwords. User passwords may be encoded and stored in the directory, which prevents clear passwords from being accessed by any users including the system administrators.

The administrator may configure the server to encode userPassword attribute values in either a one-way encoding format or a two-way encoding format.

One-way encoding formats:

• SHA-1
• crypt

After the server is configured, any new passwords (for new users) or modified passwords (for existing users) are encoded before they are stored in the directory database. The encoded passwords are tagged with the encoding algorithm name so that passwords encoded in different formats can coexist in the directory. When the encoding configuration is changed, existing encoded passwords remain unchanged and continue to work.

For applications which require retrieval of clear passwords, such as middle-tier authentication agents, the directory administrator needs to configure the server to perform either a two-way encoding or no encryption on user passwords. In this instance, the clear passwords stored in the directory are protected by the directory ACL mechanism.

Two-way encoding format:

• imask

imask, a 2-way masking option, is provided to allow values of the userPassword attribute to be encoded in the directory and retrieved as part of an entry in the original clear format. Some applications such as middle-tier authentication servers require passwords to be retrieved in clear, however, corporate security policies might prohibit storing clear passwords in a secondary permanent storage. This option satisfies both requirements.

A simple bind will succeed if the password provided in the bind request matches with any of the multiple values of the userPassword attribute.

When you configure the server using Web Administration, you can select one of the following four encryption options:

None

No encryption. Passwords are stored in the clear text format.

crypt

Passwords are encoded by the UNIX^(R) crypt encoding algorithm before they are stored in the directory.

SHA-1

Passwords are encoded by the SHA-1 encoding algorithm before they are stored in the directory.

imask

Passwords are encoded by the imask algorithm before they are stored in the directory, and are retrieved as part of an entry in the original clear format.

The default option is imask. The change is registered in a password encryption directive of the server configuration file:

ibm-SlapdPwEncryption: imask

The server configuration file is located in:

<installation path>\etc\ibmslapd.conf 

In addition to userPassword, values of the secretKey attribute are always "imask" encoded in the directory. Unlike userPassword, this encoding is enforced for values of secretKey. No other option is provided. The secretKey attribute is an IBM defined schema. Applications may use this attribute to store sensitive data that need to be always encoded in the directory and retrieve the data in clear via the directory access control.

Consult the Installation and Configuration Guide for additional information about the configuration file.

To change the type of encryption using the command line, for example to crypt, issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -f <filename>
 

where <filename>contains:

dn: cn=configuration
changetype: modify
replace: ibm-slapdPWEncryption
ibm-slapdPWEncryption: crypt

To update the settings dynamically, issue the following ldapexop command:

ldapexop -D <adminDN> -w <adminPW> -op readconfig -scope single 
        "cn=configuration" ibm-slapdPWEncryption

Notes:

1. When 'imask' is used as the server password encryption method, only the first 46 characters of a password entered are effective. Any characters after the 46th character will be ignored and considered as matched. Similarly, if the UNIX 'crypt' method is used, only the first 8 characters will be effective. Also since the value of SecretKey is encrypted in the database using the 'imask' encryption, the SecretKey values which are longer than 46 characters will not be maintained.

2. A one-way encoded password can be used for password matching but it cannot be decrypted. During user login the login password is encoded and compared with the stored version for matching verification.

Setting Kerberos

The IBM Directory supports Kerberos Version 1.3 servers, such as the IBM Network Authentication Service, on AIX servers and clients, and Windows NT^(R) and Windows 2000 clients only.

Note:

You must have a Kerberos client installed to use Kerberos authentication.

Under Network Authentication Service, a client (generally either a user or a service) sends a request for a ticket to the Key Distribution Center (KDC). The KDC creates a ticket-granting ticket (TGT) for the client, encrypts it using the client's password as the key, and sends the encrypted TGT back to the client. The client then attempts to decrypt the TGT, using its password. If the decryption is successful, the client retains the decrypted TGT, indicating proof of the client's identity.

The TGT, which expires at a specified time, permits the client to obtain additional tickets that give permission for specific services. The requesting and granting of these additional tickets does not require user intervention.

Network Authentication Service negotiates authenticated, optionally encrypted communications between two points on the network. It can enable applications to provide a layer of security that is not dependent on which side of a firewall either client is on. Because of this, Network Authentication Service can play a vital role in the security of your network.

You need to create an LDAP server servicename in the key distribution center (KDC) using the principal name ldap/<hostname>.<mylocation>.<mycompany>.com.

Note:

An environment variable "LDAP_KRB_SERVICE_NAME" is used to determine the case of the LDAP Kerberos service name. If the variable is set to 'LDAP' then the uppercase LDAP Kerberos service name is used. If the variable is not set, then the lower case 'ldap' is used. This environment variable is used by both the ldap client and the server. By default this variable is not set. See Kerberos service name change for more detailed information.

Network Authentication Service provides the following components:

Key distribution center

The KDC is a trusted server that has access to the private keys of all the principals in a realm. The KDC is composed of two parts: the Authentication Server (AS) and the Ticket Granting Server (TGS). The AS handles initial client authentication by issuing a TGT. The TGS issues service tickets that can be used by the client to authenticate to a service.

Administration server

The administration server provides administrative access to the Network Authentication Service database. This database contains the principals, keys, policies and other administrative information for the realm. The administration server allows adding, modifying, deleting and viewing principals and policies.

Password change service

The password change service allows users to change their passwords. The password change service is provided by the administration server.

Client programs

Client programs are provided to manipulate credentials (tickets), manipulate keytab files, change passwords and perform other basic Network Authentication Service operations.

Application programming interfaces (APIs)

Libraries and header files are provided to allow the development of secure distributed applications. The APIs provided are described in the Application Development Reference.

Using Web Administration:

Expand the Manage server properties category in the navigation area of the Web Administration Tool, select the Kerberos tab.

1. Check the Enable Kerberos authentication check box to enable Kerberos authentication.
2. Check the Map Kerberos IDs to LDAP DNs check box to enable the directory administrator to use the existing set of ACL data with the Kerberos authentication method. See Identity mapping for Kerberos for more information.
3. Enter the Kerberos realm using the format hostName.domainName, for example, TEST.AUSTIN.IBM.COM.
4. Enter the path and file name of the Kerberos keytab file. This file contains the private key of the LDAP server, as associated with its kerberos account. This file, and the SSL key database file, should be protected.
5. Enter the Alternate administrator ID using the format ibm-kn=value@realm, for example, ibm-kn=root@TEST.AUSTIN.IBM.COM.
6. When you are finished, click OK to apply your changes or click Cancel to exit this panel without making any changes.

Using the command line:

To create a Kerberos entry issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -f <filename>
 

where <filename>contains:

dn: cn=Kerberos, cn=Configuration
cn: Kerberos
ibm-slapdKrbAdminDN: ibm-kn=admin@MYREALM.AUSTIN.IBM.COM
ibm-slapdKrbEnable: true
ibm-slapdKrbIdentityMap: true
ibm-slapdKrbKeyTab: /keytabs/mykeytab.keytab
ibm-slapdKrbRealm: MYREALM.AUSTIN.IBM.COM
objectclass: ibm-slapdKerberos
objectclass: ibm-slapdconfigEntry
objectclass: top

To modify a Kerberos entry, for example to change the keytab file, issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -f <filename>

where <filename> contains:

dn: cn=Kerberos, cn=Configuration
changetype: modify
replace: ibm-slapdKrbKeyTab
ibm-slapdKrbKeyTab: /keytabs/mynewkeytab.keytab

Using Kerberos

Before you can us the command line for Kerberos authentication, you need to do a Kerberos initialization. Issue the following command:

kinit <kerberos_principlename>@<realm_name>

To use Kerberos authentication you must specify the -m option with the GSSAPI parameter on the ldapadd and ldapsearch commands. For example:

ldapsearch  -V 3 -m GSSAPI -b <"cn=us"> objectclass=*

Identity mapping for Kerberos

Identity mapping enables the directory administrator to use the existing set of ACL data with the Kerberos authentication method. The ACL for the IBM Directory is based on the Distinguished Name (DN) assigned to the client connected to the directory server. The access rights are based on what permissions have been granted for that DN and the permissions for any groups containing that DN as a member. If the bind method for GSSAPI is used (that is, Kerberos is used for authenticating to the server), the DN is something like IBM-KN=your_principal@YOUR_REALM_NAME. This type of DN can be used as members of access groups or access IDs. You can also use the Kerberos Identity Mapping feature to grant access rights for this DN to an entry already in the directory.

For example, if there is an entry in the directory for Reginald Bender:

dn: cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US
objectclass: top
objectclass: person
objectclass: organizationalperson
cn: Reginald Bender
sn: Bender
aclentry: access-id:CN=THIS:critical:rwsc
aclentry: group:CN=ANYBODY:normal:rsc
userpassword: cL1eNt

The access rights for this entry allow anyone binding with the DN "cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US" to view critical data such as the password, but no one else.

If Reginald Bender used Kerberos to bind to the server, his DN could be something like IBM-KN=rbender@SW.REALM_1. If identity mapping is not enabled on the server, he is not allowed to view his own entry's password.

If identity mapping is enabled, he can view the password if this entry were changed to include:

dn: cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US...
objectclass: ibm-securityidentities
altsecurityidentities: Kerberos:rbender@SW.REALM_1

When Reginald Bender binds to the directory server, the server first searches the whole directory to determine if the directory is a KDC (Key Distribution Center) account registry. If it is not, the server searches the directory for any entry containing an altsecurityidentities attribute with a value matching the Kerberos user principal and realm. In this example, rbender is the user principal and SW.REALM_1 is the realm. This is the default for the Kerberos identity mapping. The bind fails if more than one entry has an attribute with this value. The mapping must be one-to-one. If the mapping is successful, Reginald Bender has all of the access rights for "cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US", including any access groups that has this as a member.

The IBM Directory Server can be used to contain Kerberos account information (krbRealmName-V2 = <realm_name> and krbPrincipalName = <princ_name>@<realm_name>) to serve as the backing store for a KDC.

The server with Kerberos identity mapping enabled first searches the directory for entries with objectclass krbRealm-V2 and krbRealmName-V2 =<realm_name>, such as:

dn: krbRealmName-V2=SW.REALM_1, o=SecureWay.com, c=US
objectclass:  krbRealm-V2
krbReamlName-V2: SW.REALM_1

If no entries are found, the server uses the default Kerberos identity mapping described previously. If more than one entry is found, the bind fails.

However, if the directory contains the single entry:

dn: krbRealmName-V2=SW.REALM_1, ou=Group, o=SecureWay.com, c=US
objectclass:  krbRealm-V2
krbRealmName-V2: SW.REALM_1
krbPrincSubtree: ou=internal users,o=SecureWay.com, c=US
krbPrincSubtree: ou=external users,o=SecureWay.com, c=US

The server searches each subtree listed as a value of krbPrincSubtree for an entry with an attribute krbPrincipalName.

In this release, for identity mapping to work for Reginald Bender, you need to add two attributes to the "cn=Reginal Bender, ou=internal users, o=SecureWay.com, c=US" entry:

objectclass: extensibleObject
krbPrincipalName: rbender@SW.REALM_1
 

Depending on whether the directory is a KDC account registry, the final entry is:

dn: cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US...
objectclass: ibm-securityidentities
altsecurityidentities: Kerberos:rbender@SW.REALM_1...
 

or for a KDC account registry:

dn: cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US ...
objectclass: extensibleObject
krbPrincipalName: rbender@SW.REALM_1

In either case, the client is mapped to "cn=Reginald Bender, ou=internal users, o=SecureWay.com, c=US".

If a DN is not mapped because no entry is found, the mapping fails but the bind is still successful. However, if more than one DN is mapped, the bind fails.

Identity mapping enables the existing ACLs to work with Kerberos authentication. A client using Kerberos with a mapped identity has two distinct identities, both of which are evaluated in granting access.

Identity mapping has some costs. The internal searches at bind time impact performance and identity mapping requires additional setup to add the appropriate attributes to the entries to be mapped.

In this release, if default identity mapping is used, the administrator (either Kerberos or LDAP) must make sure that the data in the KDC and the data in the LDAP server are synchronized. If the data is not synchronized, incorrect results might be returned because of incorrect ACL evaluation.

Note:

The object class, such as KrbPrincipal and the attributes such as KrbPrincSubtree, KRbAliasedObjectName, and KrbHintAliases are used to define a IBM Directory as a Kerberos KDC. See the Kerberos documentation for more information.

Managing the IBM Directory schema

A schema is a set of rules that governs the way that data can be stored in the directory. The schema defines the type of entries allowed, their attribute structure and the syntax of the attributes.

Data is stored in the directory using directory entries. A entry consists of an object class, which is required, and its attributes. Attributes can be either required or optional. The object class specifies the kind of information that the entry describes and defines the set of attributes it contains. Each attribute has one or more associated values. See Working with directory entries for additional information about entries.

The schema for the IBM Directory Version 5.1 is predefined, however, you can modify the schema, if you have additional requirements.

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

The schema has more configuration information than that included in the LDAP Version 3 Request For Comments (RFCs) or standard specifications. For example, for a given attribute, you can state which indexes must be maintained. This additional configuration information is maintained in the subschema entry as appropriate. An additional object class is defined for the subschema entry IBMsubschema , which has "MAY" attributes that hold the extended schema information.

IBM Directory Server requires that the schema defined for a naming context be stored in a special directory entry, "cn=schema". The entry contains all of the schema defined for the server. To retrieve schema information, you can perform an ldap_search by using the following:

 DN: "cn=schema", search scope: base, filter: objectclass=subschema
 or objectclass=*

The schema provides values for the following attribute types:

• objectClasses (See Working with object classes.)
• attributeTypes (See Working with attributes.)
• IBMAttributeTypes (See The IBMAttributeTypes attribute type.)
• matching rules (See Matching rules).
• ldap syntaxes (See Attribute syntax).

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

A sample schema entry might contain:

 objectclasses=( 1.3.6.1.4.1.1466.101.120.111
                 NAME 'extensibleObject'
                 SUP top AUXILIARY )
 
  objectclasses=(  2.5.20.1
                  NAME 'subschema'
                  AUXILIARY MAY
                      ( dITStructureRules
                     $ nameForms
                     $ ditContentRules
                     $ objectClasses
                     $ attributeTypes
                     $ matchingRules
                     $ matchingRuleUse  ) )
  objectclasses=( 2.5.6.1
                  NAME 'alias'
                  SUP top STRUCTURAL
                  MUST aliasedObjectName )
 
  attributeTypes {
      ( 2.5.18.10 NAME 'subschemaSubentry' EQUALITY distinguishedNameMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION
        SINGLE-VALUE USAGE directoryOperation )
      ( 2.5.21.5 NAME 'attributeTypes'
          EQUALITY objectIdentifierFirstComponentMatch
          SYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
      ( 2.5.21.6 NAME 'objectClasses'
          EQUALITY objectIdentifierFirstComponentMatch
          SYNTAX 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' )
              ( 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 attribute values of a given attribute type be provided in a single production.

The schema information can be modified through the ldap_modify API. Consult the 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. To delete a schema entity, provide the oid in parenthesis (oid). You also can provide a full description. You can add or replace a schema entry with the LDAP Version 3 definition or with the IBM attribute extension definition or with both definitions.

Common schema support

The IBM Directory supports standard directory schema as defined in the following:

• The Internet Engineering Task Force (IETF) LDAP Version 3 RFCs, such as RFC 2252 and 2256.
• The Directory Enabled Network (DEN)
• The Common Information Model (CIM) from the Desktop Management Task Force (DMTF)
• The Lightweight Internet Person Schema (LIPS) from the Network Application Consortium

This version of LDAP includes the LDAP Version 3 defined schema in the default schema configuration. It also includes the DEN schema definitions.

IBM also provides a set of extended common schema definitions that other IBM products share when they exploit the LDAP directory. They include:

• Objects for white page applications such as eperson, group, country, organization, organization unit and role, locality, state, and so forth
• Objects for other subsystems such as accounts, services and access points, authorization, authentication, security policy, and so forth.

Working with object classes

An object class specifies a set of attributes used to describe an object. For example, if you created the object class tempEmployee, it could contain attributes associated with a temporary employee such as, idNumber, dateOfHire, or assignmentLength. You can add custom object classes to suit the needs of your organization. The IBM Directory Server schema provides some basic types of object classes, including:

• Groups
• Locations
• Organizations
• People

Note:

Object classes that are specific to the IBM Directory Server have the prefix 'ibm-'.

Defining object classes

Object classes are defined by the characteristics of type, inheritance, and attributes.

Object class type

An object class can be one of three types:

Structural:

Every entry must belong to one and only one structural object class, which defines the base contents of the entry. This object class represents a real world object. Because all entries must belong to a structural object class, this is the most common type of object class.

Abstract:

This type is used as a superclass or template for other (structural) object classes. It defines a set of attributes that are common to a set of structural object classes. These object classes, if defined as subclasses of the abstract class, inherit the defined attributes. The attributes do not need to be defined for each of the subordinate object classes.

Auxiliary:

This type indicates additional attributes that can be associated with an entry belonging to a particular structural object class. Although an entry, can belong to only a single structural object class, it may belong to multiple auxiliary object classes.

Object Class Inheritance

This version of the IBM Directory Server supports object inheritance for object class and attribute definitions. A new object class can be defined with parent classes (multiple inheritance) and the additional or changed attributes.

Each entry is assigned to a single structural object class. All object classes inherit from the abstract object class top. They can also inherit from other object classes. The object class structure determines the list of required and allowed attributes for a particular entry. Object class inheritance depends on the sequence of object class definitions. An object class can only inherit from object classes that precede it. For example, the object class structure for a person entry might be defined in the LDIF file as:

objectClass: top 
objectClass: person 
objectClass: organizationalPerson 
 

In this structure, the organizationalPerson inherits from the person and the top object classes, while person object class only inherits from the top object class. Therefore, when you assign the organizationalPerson object class to an entry, it automatically inherits the required and allowed attributes from the superior object class. In this case, the person object class.

Schema update operations are checked against the schema class hierarchy for consistency before being processed and committed.

Attributes

Every object class includes a number of required attributes and optional attributes. Required attributes are the attributes that must be present in entries using the object class. Optional attributes are the attributes that may be present in entries using the object class.

Viewing object classes

You can view the object classes in the schema using either the Web Administration Tool, the preferred method or using the command line.

Using Web Administration:

Expand Schema management in the navigation area and click Manage object classes. A read-only panel is displayed that enables you to view the object classes in the schema and their characteristics. The object classes are displayed in alphabetical order. You can move one page backwards or forward by clicking Previous or Next. The field next to these buttons identifies the page that you are on. You can also use the drop down menu of this field to skip to a specific page. The first object class listed on the page is displayed with the page number to help you locate the object class you want to view. For example, if you were looking for the object class person, you expand the drop down menu and scroll down until you see Page 14 of 16 nsLiServer and Page 15 of 16 printerLPR. Because person is alphabetically between nsLiServer and printerLPR, you select Page 14 and click Go.

You can also display the object classes sorted by type. Select Type and click Sort. The object classes are sorted alphabetically within their type, Abstract, Auxiliary, or Structural. Similarly you can reverse the list order by selecting Descending and clicking Sort.

After you have located the object class that you want, you can view its type, inheritance, required attributes, and optional attributes. Expand the drop down menus for inheritance, required attributes, and optional attributes to see the full listings for each characteristic.

You can choose the object class operations you want to perform from the right-hand tool bar, such as:

• Add
• Edit
• Copy
• Delete

When you are finished click Close to return to the IBM Directory Server Welcome panel.

Using the command line:

To view the object classes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* objectclasses

Adding an object class

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage object classes. To create a new object class:

1. Click Add.

   Note:

   You can also access this panel by expanding Schema management in the navigation area, then click Add an object class.

2. At the General properties tab:
   • Enter the Object class name. This is a required field, and is descriptive of the function of the object class. For example, tempEmployee for an object class used to track temporary employees.
   • Enter a Description of the object class, for example, The object class used for temporary employees.
   • Enter the OID for the object class. This is a required field. See Object identifier (OID). If you do not have an OID, you can use the Object class name appended with -oid. For example, if the object class name is tempEmployee, then the OID is tempEmployee-oid. You can change the value of this field.
   • Select a Superior object class from the drop-down list. This determines the object class from which other attributes are inherited. Typically the Superior object class is top, however, it can be another object class. For example, a superior object class for tempEmployee might be ePerson.
   • Select an Object class type. See Object class type for additional information about object class types.
   • Click the Attributes tab to specify the required and the optional attributes for the object class and view the inherited attributes, or click OK to add the new object class or click Cancel to return to Manage object classes without making any changes.
3. At the Attributes tab:
   • Select an attribute from the alphabetical list of Available attributes and click Add to required to make the attribute required or click Add to optional to make the attribute optional for the object class. The attribute is displayed in the appropriate list of selected attributes.
   • Repeat this process for all the attributes you want to select.
   • You can move an attribute from one list to another or delete the attribute from the selected lists by selecting it and clicking the appropriate Move to or Delete button.
   • You can view the lists of required and optional inherited attributes. Inherited attributes are based on the Superior object class selected on the General tab. You cannot change the inherited attributes. However, if you change the Superior object class on the General tab, a different set of inherited attributes is displayed.
4. Click OK to add the new object class or click Cancel to return to Manage object classes without making any changes.

Note:

If you clicked OK on the General tab without adding any attributes, you can add attributes by editing the new object class.

Using the command line:

To add an object class using the command line, issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -i <filename>
 

where <filename>contains:

dn: cn=Schema
changetype: modify
add: objectclasses
objectclasses: ( <myobjectClass-oid> NAME '<myObjectClass>' DESC '<An object class 
                 I defined for my LDAP application>' SUP '<objectclassinheritance>'
                 <objectclasstype> MAY (<attribute1> $ <attribute2>))
 

Editing an object class

Not all schema changes are allowed. See Disallowed schema changes for change restrictions.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage object classes. To edit an object class:

1. Click the radio button next to the object class that you want to edit.
2. Click Edit .
3. Select a tab:
   • Use the General tab to:
     • Modify the Description.
     • Change the Superior object class. Select a Superior object class from the drop-down list. This determines the object class from which other attributes are inherited. Typically the Superior object class is top, however, it can be another object class. For example, a superior object class for tempEmployee might be ePerson.
     • Change the Object class type. Select an object class type. See Object class type for additional information about object class types.
     • Click the Attributes tab to change the required and the optional attributes for the object class and view the inherited attributes, or click OK to apply your changes or click Cancel to return to Manage object classes without making any changes.
   • Use the Attributes tab to:

     Select an attribute from the alphabetical list of Available attributes and click Add to required to make the attribute required or click Add to optional to make the attribute optional for the object class. The attribute is displayed in the appropriate list of selected attributes.

     Repeat this process for all the attributes you want to select.

     You can move an attribute from one list to another or delete the attribute from the selected lists by selecting it and clicking the appropriate Move to or Delete button.

     You can view the lists of required and optional inherited attributes. Inherited attributes are based on the Superior object class selected on the General tab. You cannot change the inherited attributes. However, if you change the Superior object class on the General tab, a different set of inherited attributes is displayed.

4. Click OK to apply the changes or click Cancel to return to Manage object classes without making any changes.

Using the command line:

View the object classes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* objectclasses

To edit an object class using the command line, issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -i <filename>
 

where <filename>contains:

dn: cn=schema
changetype: modify
replace: objectclasses
objectclasses: ( <myobjectClass-oid> NAME '<myObjectClass>' DESC '<An object class 
                 I defined for my LDAP application>' SUP '<newsuperiorclassobject>'
                 <newobjectclasstype> MAY (attribute1> $ <attribute2> 
                  $ <newattribute3>) )

Copying an object class

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage object classes. To copy an object class:

1. Click the radio button next to the object class that you want to copy.
2. Click Copy.
3. Select a tab:
   • Use the General tab to:
     • Modify the object class name. The default name is the copied object class name appended with the word COPY. For example tempPerson is copied as tempPersonCOPY.
     • Modify the Description.
     • Modify the OID. The default OID is the copied object class OID appended with the word COPY. For example tempPerson-oid is copied as tempPerson-oidCOPY.
     • Change the Superior object class. Select a superior object class from the drop-down list. This determines the object class from which other attributes are inherited. Typically the Superior object class is top, however, it can be another object class. For example, a superior object class for tempEmployeeCOPY might be ePerson.
     • Change the Object class type. Select an object class type. See Object class type for additional information about object class types.
     • Click the Attributes tab to change the required and the optional attributes for the object class and view the inherited attributes, or click OK to apply your changes or click Cancel to return to Manage object classes without making any changes.
   • Use the Attributes tab to:

     Select an attribute from the alphabetical list of Available attributes and click Add to required to make the attribute required or click Add to optional to make the attribute optional for the object class. The attribute is displayed in the appropriate list of selected attributes.

     Repeat this process for all the attributes you want to select.

     You can move an attribute from one list to another or delete the attribute from the selected lists by selecting it and clicking the appropriate Move to or Delete button.

     You can view the lists of required and optional inherited attributes. Inherited attributes are based on the Superior object class selected on the General tab. You cannot change the inherited attributes. However, if you change the Superior object class on the General tab, a different set of inherited attributes is displayed.

4. Click OK to apply the changes or click Cancel to return to Manage object classes without making any changes.

Using the command line:

View the object classes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* objectclasses

Select the object class that you want to copy. Use an editor to change the appropriate information and save the changes to <filename>. The issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -i <filename>
 

where <filename>contains:

dn: cn=schema
changetype: modify
replace: objectclasses
objectclasses: ( <mynewobjectClass-oid> NAME '<mynewObjectClass>'
                DESC '<A new object class 
                 I copied for my LDAP application>'
               SUP '<superiorclassobject>'<objectclasstype> MAY (attribute1> 
               $ <attribute2> $ <attribute3>) )

Deleting an object class

Not all schema changes are allowed. See Disallowed schema changes for change restrictions.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage object classes. To delete an object class:

1. Click the radio button next to the object class that you want to delete.
2. Click Delete.
3. You are prompted to confirm deletion of the object class. Click OK to delete the object class or click Cancel to return to Manage object classes without making any changes.

Using the command line:

View the object classes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* objectclasses

Select the object class you want to delete and issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -i <filename>
 

where <filename>contains:

dn: cn=schema
changetype: modify
delete: objectclasses
objectclasses: ( <myobjectClass-oid> NAME '<myObjectClass>' DESC '<An object class 
                 I defined for my LDAP application>' SUP '<objectclassinheritance>'
                 <objectclasstype> MAY (<attribute1> $ <attribute2>))

Working with attributes

Each directory entry has a set of attributes associated with it through it's object class. While the object class describes the type of information that an entry contains, the actual data is contained in attributes. An attribute is represented by one or more name-value-pairs that hold specific data element such as a name, an address, or a telephone number. The IBM Directory Server represents data as name-value-pairs, a descriptive attribute, such as commonName (cn), and a specific piece of information, such as John Doe.

For example, the entry for John Doe might contain several attribute name-value-pairs.

dn: uid=jdoe, ou=people, ou=mycompany, c=us,
objectClass: top 
objectClass: person 
objectClass: organizationalPerson 
cn: John Doe 
sn: Doe 
givenName: Jack 
givenName: John
 

While the standard attributes are already defined in the schema file, you can create, edit, copy, or delete attributes to suit the needs of your organization.

Viewing attributes

You can view the attributes in the schema using either the Web Administration Tool, the preferred method or using the command line.

Using Web Administration:

Expand Schema management in the navigation area and click Manage attributes. A read-only panel is displayed that enables you to view the attributes in the schema and their characteristics. The attributes are displayed in alphabetical order. You can move one page backwards or forward by clicking Previous or Next. The field next to these buttons identifies the page that you are on. You can also use the drop down menu of this field to skip to a specific page. The first object class listed on the page is displayed with the page number to help you locate the object class you want to view. For example, if you were looking for the attribute authenticationUserID, you expand the drop down menu and scroll down until you see Page 3 of 62 applSystemHint and Page 4 of 62 authorityRevocatonList. Because authenticationUserID is alphabetically between applSystemHint and authorityRevocatonList, you select Page 3 and click Go.

You can also display the attributes sorted by syntax. Select Syntax and click Sort. The attributes are sorted alphabetically within their syntax. SeeAttribute syntax for a listing or the types of syntax. Similarly you can reverse the list order by selecting Descending and clicking Sort.

After you have located the attribute that you want, you can view its syntax, whether it is multi-valued, and the object classes that contain it. Expand the drop down menu for object classes to see the list of object classes for the attribute.

When you are finished click Close to return to the IBM Directory Server Welcome panel.

Using the command line:

To view the attributes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* attributeTypes IBMAttributeTypes

Adding an attribute

Use either of the following methods to create a new attribute. The Web Administration Tool is the preferred method.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage attributes. To create a new attribute:

1. Click Add.

   Note:

   You can also access this panel by expanding Schema management in the navigation area, then click Add an attribute.

2. Enter the Attribute name, for example, tempId. This is a required field and must begin with an alphabetical character.
3. Enter a Description of the attribute, for example, The ID number assigned to a temporary employee.
4. Enter the OID for the attribute. This is a required field. See Object identifier (OID). If you do not have an OID, you can use the attribute name appended with -oid. For example, if the attribute name is tempID, then the default OID is tempID-oid. You can change the value of this field.
5. Select a Superior attribute from the drop-down list. The superior attribute determines the attribute from which properties are inherited.
6. Select a Syntax from the drop-down list. See Attribute syntax for additional information about syntax.
7. Enter an Attribute length that specifies the maximum length of this attribute. The length is expressed as the number of bytes.
8. Select the Allow multiple values checkbox to enable the attribute to have multiple values. See the glossary entry for additional information about multiple values.
9. Select a matching rule from the each of the drop-down menus for equality, ordering, and substring matching rules. See the Matching rules for a complete listing of matching rules.
10. Click the IBM extensions tab to specify additional extensions for the attribute, or click OK to add the new attribute or click Cancel to return to Manage attributes without making any changes.
11. At the IBM extensions tab:
    • 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 enter a DB2 column name.
    • Modify the DB2 column name. The server generates the DB2 column name if this field is left blank. If you enter a DB2 column name, you must also enter a DB2 table name.
    • Set the Security class by selecting normal, sensitive, or critical from the drop-down list.
    • Set the Indexing rules by selecting one or more indexing rules. See Indexing rules for additional information about indexing rules.

      Note:

      At a minimum, it is recommended that you specify Equality indexing on any attributes that are to be used in search filters.

12. Click OK to add the new attribute or click Cancel to return to Manage attributes without making any changes.

Note:

If you clicked OK on the General tab without adding any extensions, you can add extensions by the editing the new attribute.

Using the command line:

The following example adds an attribute type definition for an attribute called "myAttribute", with Directory String syntax (see Attribute syntax) and Case Ignore Equality matching (see Matching rules). The IBM-specific part of the definition says that the attribute data is stored in a column named "myAttrColumn" in a table called "myAttrTable". If these names were not specified, both the column and table name would have defaulted to "myAttribute". The attribute is assigned to the "normal" access class, and values have a maximum length of 200 bytes.

ldapmodify -D <admindn> -w <adminpw> -i myschema.ldif
 

where the myschema.ldif file contains:

dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( myAttribute-oid NAME ( 'myAttribute' ) 
                 DESC 'An attribute I defined for my LDAP application' 
                 EQUALITY 2.5.13.2 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 
                 USAGE userApplications )
-
add: ibmattributetypes
ibmattributetypes: ( myAttribute-oid  DBNAME ( 'myAttrTable' 'myAttrColumn' ) 
                    ACCESS-CLASS normal LENGTH 200 )

See ldapmodify, ldapadd for more information about this command.

Editing an attribute

Not all schema changes are allowed. See Disallowed schema changes for change restrictions.

Any part of a definition can be changed before you have added entries that use the attribute. Use either of the following methods to edit an attribute. The Web Administration Tool is the preferred method.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage attributes. To edit an attribute:

1. Click the radio button next to the attribute that you want to edit.
2. Click Edit .
3. Select a tab:
   • Use the General tab to:
     • Select a tab, either:
       • General to:
         • Modify the Description
         • Change the Syntax
         • Set the Attribute length
         • Change the Multiple value settings
         • Select a Matching rule
         • Change the Superior attribute
       • Click the IBM extensions tab to edit the extensions for the attribute, or click OK to apply your changes or click Cancel to return to Manage attributes without making any changes.
       • IBM extensions, if you are using the IBM Directory Server, to:
         • Change the Security class
         • Change the Indexing rules
     • Click OK to apply your changes or click Cancel to return to Manage attributes without making any changes.
4. Click OK to apply the changes or click Cancel to return to Manage attributes without making any changes.

Using the command line:

This example adds indexing to the attribute, so that searching on it is faster. Use the ldapmodify command and the LDIF file to change the definition:

ldapmodify -D <admindn> -w <adminpw> -i myschemachange.ldif
 

Where the myschemachange.ldif file contains:

dn: cn=schema
changetype: modify
replace: attributetypes
attributetypes: ( myAttribute-oid NAME ( 'myAttribute' ) DESC 'An attribute 
                 I defined for my LDAP application' EQUALITY 2.5.13.2 
                 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
-
replace: ibmattributetypes
ibmattributetypes: ( myAttribute-oid  DBNAME ( 'myAttrTable' 'myAttrColumn' ) 
                  ACCESS-CLASS normal LENGTH 200 EQUALITY SUBSTR )

Note:

Both portions of the definition (attributetypes and ibmattributetypes) must be included in the replace operation, even though only the ibmattributetypes section is changing. The only change is adding "EQUALITY SUBSTR" to the end of the definition to request indexes for equality and substring matching.

Copying an attribute

Use either of the following methods to copy an attribute. The Web Administration Tool is the preferred method.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage attributes. To copy an attribute:

1. Click the radio button next to the attribute that you want to copy.
2. Click Copy.
3. Modify the Attribute name. The default name is the copied attribute name appended with the word COPY. For example tempID is copied as tempIDCOPY.
4. Modify a Description of the attribute, for example, The ID number assigned to a temporary employee.
5. Modify the OID. The default OID is the copied attribute OID appended with the word COPYOID. For example tempID-oid is copied as tempID-oidCOPYOID.
6. Select a Superior attribute from the drop-down list. The superior attribute determines the attribute from which properties are inherited.
7. Select a Syntax from the drop-down list. See Attribute syntax for additional information about syntax.
8. Enter a Attribute length that specifies the maximum length of this attribute. The length is expressed as the number of bytes.
9. Select the Allow multiple values checkbox to enable the attribute to have multiple values. See the glossary entry for additional information about multiple values.
10. Select a matching rule from the each of the drop-down menus for equality, ordering, and substring matching rules. See the Matching rules for a complete listing of matching rules.
11. Click the IBM extensions tab to modify additional extensions for the attribute, or click OK to apply your changes or click Cancel to return to Manage attributes without making any changes.
12. At the IBM extensions tab:
    • 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 enter a DB2 column name.
    • Modify the DB2 column name. The server generates the DB2 column name if this field is left blank. If you enter a DB2 column name, you must also enter a DB2 table name.
    • Modify the Security class by selecting normal, sensitive, or critical from the drop-down list.
    • Modify the Indexing rules by selecting one or more indexing rules. See Indexing rules for additional information about indexing rules.

      Note:

      At a minimum, it is recommended that you specify Equal indexing on any attributes that are to be used in search filters.

13. Click OK to apply your changes or click Cancel to return to Manage attributes without making any changes.

Note:

If you clicked OK on the General tab without adding any extensions, you can add or modify extensions by editing the new attribute.

Using the command line:

View the attributes contained in the schema issue the command:

ldapsearch -b cn=schema -s base objectclass=* attributeTypes IBMAttributeTypes

Select the attribute that you want to copy. Use an editor to change the appropriate information and save the changes to <filename>. Then issue the following command:

ldapmodify -D <adminDN> -w <adminPW> -i <filename>
 

where <filename>contains:

dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( <mynewAttribute-oid> NAME '<mynewAttribute>' DESC '<A new 
                 attribute I copied for my LDAP application> EQUALITY 2.5.13.2 
                 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
-
add: ibmattributetypes
ibmattributetypes: ( myAttribute-oid  DBNAME ( 'myAttrTable' 'myAttrColumn' ) 
                    ACCESS-CLASS normal LENGTH 200 )

Deleting an attribute

Not all schema changes are allowed. See Disallowed schema changes for change restrictions.

Use either of the following methods to delete an attribute. The Web Administration Tool is the preferred method.

Using Web Administration:

If you have not done so already, expand Schema management in the navigation area, then click Manage attributes. To delete an attribute:

1. Click the radio button next to the attribute that you want to delete.
2. Click Delete.
3. You are prompted to confirm deletion of the attribute. Click OK to delete the attribute or click Cancel to return to Manage attributes without making any changes.

Using the command line:

ldapmodify -D <admindn> -w <adminpw> -i myschemadelete.ldif
 

Where the myschemadelete.ldif file includes:

dn: cn=schema
changetype: modify
delete: attributetypes
attributetypes: ( myAttribute-oid NAME ( 'myAttribute' ) DESC 'An attribute 
                 I defined for my LDAP application' EQUALITY 2.5.13.2 
                 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
-
delete: ibmattributetypes
ibmattributetypes: ( myAttribute-oid  DBNAME ( 'myAttrTable' 'myAttrColumn' ) 
                     ACCESS-CLASS normal LENGTH 200 EQUALITY SUBSTR )
 

See ldapmodify, ldapadd for more information about this command.

The IBMAttributeTypes attribute type

The IBMAttributeTypes attribute can be used to define schema information not covered by the LDAP Version 3 standard for attributes. Values of IBMAttributeTypes must comply with the following grammar:

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 substring
      whsp ")"
 
   IBMAccessClass =
      "NORMAL"            / ; this is the default
      "SENSITIVE"         /
      "CRITICAL"          /
      "RESTRICTED"        /
      "SYSTEM"            /
      "OBJECT"
 
   IBMwlen = whsp len
 

Numericoid

Used to correlate the value in attributetypes with the value in IBMAttributeTypes.

DBNAME

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

ACCESS-CLASS

The access classification for this attribute type. If ACCESS-CLASS is omitted, it defaults to normal.

LENGTH

The maximum length of this attribute. The length is expressed as the number of bytes. IBM Directory Version 5.1 has a provision for specifying 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 a maximum length.

EQUALITY, ORDERING, APPROX, SUBSTR, REVERSE

If any of these attributes are used, an index is created for the corresponding matching rule. The optional length specifies the width of the indexed column. For many syntaxes, you can share a single index to implement multiple matching rules. The IBM Directory Server takes advantage of this. It assigns a length when one is not provided by the user. SLAPD can also use a shorter length than what the user requested when it makes sense to do so. For example, when the length of the index exceeds the maximum length of the attribute, the index length is ignored.

Matching rules

A matching rule provides guidelines for string comparison during a search operation. These rules are divided into three categories:

• Equality
• Ordering
• Substring

Table 5.

Table 6.

Table 7.

Note:

UTC-Time is time string format defined by ASN.1 standards. See ISO 8601 and X680. Use this syntax for storing time values in UTC-Time format. See Generalized and UTC time.

Indexing rules

Index rules attached to attributes make it possible to retrieve information faster. If only the attribute is given, no indexes are maintained. IBM Directory provides the following indexing rules:

• Equality
• Ordering
• Approximate
• Substring
• Reverse

Indexing rules specifications for attributes:

Specifying an indexing rule for an attribute controls the creation and maintenance of special indexes on the attribute values. This greatly improves the response time to searches with filters which include those attributes. The five possible types of indexing rules are related to the operations applied in the search filter.

Equality

Applies to the following search operations:

• equalityMatch '='

For example:

"cn = John Doe"
 

Ordering

Applies to the following search operation:

• greaterOrEqual '>='
• lessOrEqual '<='

For example:

"sn >= Doe"

Approximate

Applies to the following search operation:

• approxMatch '~='

For example:

"sn ~= doe"

Substring

Applies to the search operation using the substring syntax:

• substring '*'

For example:

"sn = McC*"
"cn = J*Doe"

Reverse

Applies to the following search operation:

• '*' substring

For example:

"sn = *baugh"

At a minimum, it is recommended that you specify equal indexing on any attributes that are to be used in search filters.

Attribute syntax

You can display syntax either alphabetically or by OID. Select Syntax or OID and click Sort. Similarly you can reverse the list order by selecting Descending and clicking Sort.

Table 8.

Object identifier (OID)

An object identifier (OID) is a string, of decimal numbers, that uniquely identifies an object. These objects are typically an object class or an attribute. These numbers can be obtained from the IANA (Internet Assigned Number Authority). The IANA Website is located at: http://www.iana.org/iana/.

If you do not have an OID, you can specify the object class or attribute name appended with -oid. For example, if you create the attribute tempID, you can specify the OID as tempID-oid.

The subschema entries

There is one subschema entry per server. All entries in the directory have an implied subschemaSubentry attribute type. The value of the subschemaSubentry attribute type is the DN of the subschema entry that corresponds to the entry. All entries under the same server share the same subschema 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 one MAY attribute type ('IBMattributeTypes').

The IBMsubschema object class

The IBMsubschema object class is used only in the subschema entry as follows:

( <objectClass-oid-TBD> NAME 'IBMsubschema' AUXILIARY
     MAY IBMattributeTypes )

Schema queries

The ldap_search() API can be used to query the subschema entry, as shown in the following example:

DN           : "cn=schema"    
search scope : base    
filter       : objectclass=subschema or objectclass=*

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

See the IBM Directory Version 5.1: Client SDK Programming Reference for more information about the ldap_search API.

Dynamic schema

To 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 (for example, 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 to find the schema entity to delete is objectIdentifierFirstComponentMatch.

To add or replace a schema entity, you MUST provide a LDAP Version 3 definition and you MAY provide the IBM definition. In all cases, you must provide only the definition 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 20 chars:

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 Working with attributes for examples using the Web Administration Tool and the ldapmodify command.

See the IBM Directory Version 5.1: Client SDK Programming Reference for more information about the ldap_modify API.

Access controls

Dynamic schema changes can be performed only by a replication supplier or the administrator DN.

Replication

When a dynamic schema change is performed, it is replicated just like any other ldap_modify operation.

Disallowed schema changes

Not all schema changes are allowed. Change restrictions include the following:

• Any change to the schema must leave the schema in a consistent state.
• 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 an object class may not be deleted.
• An object class that is a superclass of another may not be deleted.
• Attribute types or object classes that refer to nonexisting entities (for example, syntaxes or object classes) cannot be added.
• 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 the server are not allowed. The following schema definitions are required by the directory server. They must not be changed.

Object classes:

• accessGroup
• accessRole
• alias
• referral
• replicaObject
• top

Attributes:

• aclEntry
• aclPropagate
• aclSource
• aliasedObjectName, aliasedentryName
• businessCategory
• cn, commonName
• createTimestamp
• creatorsName
• description
• dn, distinguishedName
• entryOwner
• member
• modifiersName
• modifyTimestamp
• name
• o, organizationName, organization
• objectClass
• ou, organizationalUnit, organizationalUnitName
• owner
• ownerPropagate
• ownerSource
• ref
• replicaBindDN
• replicaBindMethod
• replicaCredentials, replicaBindCredentials
• replicaHost
• replicaPort
• replicaUpdateTimeInterval
• replicaUseSSL
• seeAlso

Syntaxes:

All

Matching rules:

All

Schema checking

When the server is initialized, the schema files are read and checked for consistency and correctness. If the checks fail, the server fails to initialize and issues an error message. During any dynamic schema change, the resulting schema is also checked for consistency and correctness. If the checks fail, an error is returned and the change fails. Some checks are part of the grammar (for example, an attribute type can have at most one supertype, or an object class can have any number of superclasses).

The following items are checked for attribute types:

• Two different attribute types cannot have the same name or OID.
• The inheritance hierarchy of attribute types does not have cycles.
• The supertype of an attribute type must also be defined, although its definition might be displayed later, or in a separate file.
• If an attribute type is a subtype of another, they both have the same USAGE.
• All attribute types have a syntax either directly defined or inherited.
• Only operational attributes can be marked as NO-USER-MODIFICATION.

The following items are checked for object classes:

• Two different object classes cannot have the same name or OID.
• The inheritance hierarchy of object classes does not have cycles.
• The superclasses of an object class must also be defined, although its definition might appear later or in a separate file.
• 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.
• Every structural object class is a direct or indirect subclass of top.
• If an abstract object class has superclasses, the superclasses must also be abstract.

Checking an entry against the schema

When an entry is added or modified through an LDAP operation, the entry is checked against the schema. By default, all checks listed in this section are performed. However, you can selectively disable some of them by providing an ibm-slapdSchemaCheck value to the ibmslapd.conf configuration directive. See the IBM Directory Server Version 5.1 Installation and Configuration Guide for information about schema configuration attributes.

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

With respect to object classes:

• Must have at least one value of attribute type "objectClass".
• 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.
• 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 the entry has, it also has a structural or auxiliary object class that inherits directly or indirectly from that abstract object class.
• Must have at least one structural object class.
• 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 derived object class is called the "immediate" or "base structural" object class of the entry, or simply the "structural" object class of the entry.
• Cannot change its immediate structural object class (on ldap_modify).
• 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 not provided with the entry, then it is automatically added.

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

• The set of MUST attribute types for the entry is calculated as the union of the sets of MUST attribute types of all of its object classes, including the implied inherited object classes. If the set of MUST attribute types for the entry is not a subset of the set of attribute types contained by the entry, the entry is rejected.
• The set of MAY attribute types for the entry is calculated as the union of the sets of MAY attribute types of all of its object classes, including the implied inherited object classes. If the set of attribute types contained by the entry is not a subset of the union of the sets of MUST and MAY attribute types for the entry, the entry is rejected.
• If any of the attribute types defined for the entry are marked as NO-USER-MODIFICATION, the entry is rejected.

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

• For every attribute type contained by the entry, if the attribute type is single-valued and the entry has more than one value, the entry is rejected.
• For every attribute value of every attribute type contained by the entry, if its syntax does not comply with the syntax checking routine for the syntax of that attribute, the entry is rejected.
• For every attribute value of every attribute type contained by the entry, if its length is greater than the maximum length assigned to that attribute type, the entry is rejected.

The validity of the DN is checked as follows:

• The syntax is checked for compliance with the BNF for DistinguishedNames. If it does not comply, the entry is rejected.
• It is verified that the RDN is made up with only attribute types that are valid for that entry.
• It is verified that the values of attribute types used in the RDN appear in the entry.

DEN schema support

The Directory-Enabled Network (DEN) specification defines a standard schema form that stores and describes the relationships among objects that represent users, applications, network elements, and networking services.

To support DEN, the IBM Directory Server provides the following features:

• Subclassing (class inheritance). Class definitions can be created from existing definitions through subclassing. The new class definition inherits the properties from the parent class definition. The SUP option in the object class definition is used to specify the parent (or superior) object classes.
• LDAP syntaxes required by DEN, which include the following:
  • Boolean
  • DN
  • Directory String
  • Generalized Time
  • UTC Time
  • IA5 String
  • Integer

iPlanet compatibility

The parser used by the IBM Directory Server allows the attribute values of schema attribute types (objectClasses and attributeTypes ) to be specified using the grammar of iPlanet. For example, descrs and numeric-oids can be 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 an attribute value in a file, the whole file is replaced by one where all attribute values follow the IBM Directory Version 5.1 specifications. Because the parser used on the files and on ldap_modify requests is the same, an ldap_modify that uses the iPlanet grammar for attribute values is also handled correctly.

When a query is made on the subschema entry of a iPlanet server, the resulting entry can have more than one value for a given OID. For example, if a certain attribute type has two names (such as 'cn' and 'commonName'), then the description of that attribute type is provided twice, once for each name. The IBM Directory Server can parse a schema where the description of a single attribute type or object class appears multiple times with the same description (except for NAME and DESCR). However, when the IBM Directory Server publishes 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 how iPlanet 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 the IBM Directory Server describes it:

  ( 2.5.4.3 NAME ( 'cn' 'commonName' ) SUP name )

The IBM Directory Server supports subtypes. If you do not want 'cn' to be a subtype of name (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 names after '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 used interchangeably within the schema or for entries added to the directory.

Generalized and UTC time

There 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/99
4/2/99
99/2/4
4.2.1999
04-FEB-1999

as well as many other notations.

IBM Directory Server standardizes the timestamp representation by requiring the LDAP servers to support two syntaxes:

• 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 is measured in Coordinated Universal Time, append a capital letter Z to a time or a 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 to the coordinated universal time.

  If you designate an optional fraction of a second, a period or a comma is required. For local time differential, a '+' or a '-' must precede the hour-minute value

• 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 optional second fields. As in GeneralizedTime, an optional time differential can be specified. For example, if local time is a.m. on 2 January 1999 and the coordinated universal time is 12 noon on 2 January 1999, the value of UTCTime is either:

  "9901021200Z"
       or
  "9901020700-0500"
  

  If the local time is a.m. on 2 January 2001 and the coordinated universal time is 12 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 not recommended.

The supported matching rules are generalizedTimeMatch for equality and generalizedTimeOrderingMatch for inequality. Substring search is not allowed. For example, the following filters are valid:

 generalized-timestamp-attribute=199910061030
 utc-timestamp-attribute>=991006
 generalized-timestamp-attribute=*

The following filters are not valid:

generalized-timestamp-attribute=1999*
utc-timestamp-attribute>=*1010

Replication

Replication is a technique used by directory servers to improve performance and reliability. The replication process keeps the data in multiple directories synchronized.

Replication provides two main benefits:

• Redundancy of information - replicas back up the content of their supplier servers.
• Faster searches - search requests can be spread among several different servers, all having the same content, instead of a single server. This improves the response time for the request completion.

Replication topology

Replication topology is managed in a new way in the IBM Directory Server Version 5.1. Some terminology used in describing replication:

Cascading replication

A replication topology in which there are multiple tiers of servers. A peer/master server replicates to a set of read-only (forwarding) servers which in turn replicate to other servers. Such a topology off-loads replication work from the master servers.

Consumer server

A server which receives changes through replication from another (supplier) server.

Credentials

Identify the method and required information that the supplier uses in binding to the consumer. For simple binds, this includes the DN and password. The credentials are stored in an entry the DN of which is specified in the replica agreement.

Forwarding server

A read-only server that replicates all changes sent to it. This contrasts to a peer/master server in that a peer/master server does not replicate changes sent to it from another peer/master server; it only replicates changes that are originally made on the peer/master server.

Master server

A server which is writable (can be updated) for a given subtree.

Nested subtree

A subtree within a replicated subtree of the directory.

Peer server

The term used for a master server when there are multiple masters for a given subtree.

Replication agreement

Information contained in the directory that defines the 'connection' or 'replication path' between two servers. One server is called the supplier (the one that sends the changes) and the other is the consumer (the one that receives the changes). The agreement contains all the information needed for making a connection from the supplier to the consumer and scheduling replication.

Replication context

Identifies the root of a replicated subtree. The ibm-replicationContext auxiliary object class may be added to an entry to mark it as the root of a replicated area. The configuration information related to replication is maintained in a set of entries created below a replication context.

Replica group

The first entry created under a replication context has objectclass ibm-replicaGroup and represents a collection of servers participating in replication. It provides a convenient location to set ACL's to protect the replication topology information. The administration tools currently support one replica group under each replication context, named ibm-replicagroup=default.

Replica subentry

Below a replica group entry, one or more entries with objectclass ibm-replicaSubentry may be created; one for each server participating in replication as a supplier. The replica subentry identifies the role the server plays in replication: master or read-only. A read-only server might, in turn, have replication agreements to support cascading replication.

Replicated subtree

A portion of the DIT that is replicated from one server to another. Under this design, a given subtree can be replicated to some servers and not to others. A subtree can be writable on a given server, while other subtrees may be read-only.

Schedule

Replication can be scheduled to occur at particular times, with changes on the supplier accumulated and sent in a batch. The replica agreement contains the DN for the entry that supplies the schedule.

Supplier server

A server which sends changes to another (consumer) server.

Specific entries in the directory are identified as the roots of replicated subtrees, by adding the ibm-replicationContext objectclass to them. Each subtree is replicated independently. The subtree continues down through the directory information tree (DIT) until reaching the leaf entries or other replicated subtrees. Entries are added below the root of the replicated subtree to contain the replication configuration information. These entries are one or more replica group entries, under which are created replica subentries. Associated with each replica subentry are replication agreements that identify the servers that are supplied (replicated to) by each server, as well as defining the credentials and schedule information.

Through replication, a change made to one directory is propagated to one or more additional directories. In effect, a change to one directory shows up on multiple different directories. The IBM Directory supports an expanded master-slave replication model. Replication topologies are expanded to include:

• Replication of subtrees of the Directory Information Tree (DIT) to specific servers
• A multi-tier topology referred to as cascading replication
• Assignment of server role (master or replica) by subtree.
• Multiple master servers, referred to as peer to peer replication.

The advantage of replicating by subtrees is that a replica does not need to replicate the entire directory. It can be a replica of a part, or subtree, of the directory.

The expanded model changes the concept of master and replica. These terms no longer apply to servers, but rather to the roles that a server has regarding a particular replicated subtree. A server can act as a master for some subtrees and as a replica for others. The term, master, is used for a server that accepts client updates for a replicated subtree. The term, replica, is used for a server that only accepts updates from other servers designated as a supplier for the replicated subtree.

There are three types of directories as defined by function: master/peer, cascading, and read-only.

Table 9. Server roles

You can request updates on a replica server, but the update is actually forwarded to the master server by returning a referral to the client. If the update is successful, the master server then sends the update to the replicas. Until the master has completed replication of the update, the change is not reflected on the replica server where it was originally requested. If the replication fails, it is repeated even if the master is restarted. Changes are replicated in the order in which they are made on the master.

If you are no longer using a replica, you must remove the replica agreement from the supplier. Leaving the definition causes the server to queue up all updates and use unnecessary directory space. Also, the supplier continues trying to contact the missing consumer to retry sending the data.

Replication agreements

A replication agreement is an entry in the directory with the object class ibm-replicationAgreement created beneath a replica subentry to define replication from the server represented by the subentry to another server. These objects are similar to the replicaObject entries used by prior versions of the Directory Server. The replication agreement consists of the following items:

• A user friendly name, used as the naming attribute for the agreement.
• An LDAP URL specifying the server, port number, and whether SSL should be used.
• The consumer server id, if known -- 'unknown' for a server whose server id is not known (as in a server running a previous release).
• The DN of an object containing the credentials used by the supplier to bind to the consumer.
• An optional DN pointer to an object containing the schedule information for replication. If the attribute is not present, changes are replicated immediately.

The user friendly name might be the consumer server name or some other descriptive string.

The consumer server id is used by the administrative GUI to traverse the topology. Given the consumer's server ID, the GUI can find the corresponding subentry and its agreements. To aid in enforcing the accuracy of the data, when the supplier binds to the consumer, it retrieves the server IDfrom the root DSE and compares it to the value in the agreement. A warning is logged if the server IDs do not match.

Because the replication agreement can be replicated, a DN to a credentials object is used. This allows the credentials to be stored in a nonreplicated area of the directory. Replicating the credentials objects (from which 'clear text' credentials must be obtainable) represents a potential security exposure. The cn=localhost suffix is an appropriate default location for creating credentials objects. Use of a separate object also makes it easier to support various authentication methods; new object classes can be created rather than trying to make sense of numerous optional attributes.

Object classes are defined for each of the supported authentication methods:

• Simple bind
• SASL EXTERNAL mechanism with SSL
• Kerberos authentication

You can designate that part of a replicated subtree not be replicated by adding the ibm-replicationContext auxiliary class to the root of the subtree, without defining any replica subentries.

Note:

The Web Administration Tool also refers to agreements as 'queues' when referring to the set of changes that are waiting to be replicated under a given agreement.

Defining replication topology

To define a replication topology, you must

1. Create a master server and define what it contains. Select the subtree that you want to be replicated and specify the server as the master.
2. Create credentials to be used by the supplier.
3. Create a replica server.
4. Export data to the replica.

Creating a replicated subtree (master server)

Note:

The server must be running to perform this task.

This task designates an entry as the root of an independently replicated subtree and creates a ibm-replicasubentry representing this server as the single master for the subtree. To create a replicated subtree, you must designate the subtree that you want the server to replicate. Expand the Replication management category in the navigation area and click Manage topology.

If the entry that you trying to add is not a suffix in the server, before you can use the Add subtree function, you must ensure that its ACLs defined as follows:

For non-filtered ACLs:

ownersource: <same as the entry DN>
ownerpropagate: TRUE
 
aclsource: <same as the entry DN>
aclpropagate: TRUE

For filtered ACLs:

ibm-filteraclinherit: FALSE

To satisfy the ACL requirements, if the entry is not a suffix in the server, edit the ACL for that entry in the Manage entries panel. Select the entry and click Edit ACL. If you want to add Non-fltered ACLs, select that tab and add an entry cn=this with the role access-id for both ACLs and owners. Ensure that Propagate ACLs and Propagate owner are checked. If you want to add Fltered ACLs select that tab and add an entry cn=this with the role access-id for both ACLs and owners. Ensure that Accumulate filtered ACLs is unchecked and that Propagate owner is checked. See Working with Access Control Lists for more detailed information.

• Click Add subtree.
• Enter the DN of the subtree that you want to replicate or click Browse to expand the entries to select the entry that is to be the root of the subtree.
• Enter the master server referral URL. This must be in the form of an LDAP URL, for example:

  ldap://<myservername>.<mylocation>.<mycompany>.com
  

  Note:

  The master server referral URL is optional. It is used only:

  • If server contains (or will contain) any read-only subtrees.
  • To define a referral URL that is returned for updates to any read-only subtree on the server.

• Click OK.
• The new server is displayed on the Manage topology panel under the heading Replicated subtrees.

To add additional masters (peers), you first add the server as a read-only replica of the existing masters (see Creating a replica server), initialize the directory data, and then promote the server to be a master (see Moving or promoting a server).

Initially, the ibm-replicagroup object created by this process inherits the ACL of the root entry for the replicated subtree. These ACLs might be inappropriate for controlling access to the replication information in the directory.

For the Add subtree operation to be successful, the entry DN which you are adding must have correct ACLs, if it is not a suffix in the server.

For Non-filtered ACLs :

• ownersource : <the entry DN>
• ownerpropagate : TRUE
• aclsource : <the entry DN>
• aclpropagate: TRUE

Filtered ACLs :

• ownersource : <the entry DN>
• ownerpropagate : TRUE
• ibm-filteraclinherit : FALSE
• ibm-filteraclentry : <any value>

Use the Edit ACLs function to set ACLs for the replication information associated with the newly created replicated subtree (see Editing access control lists).

Note:

On the Linux, Solaris, and HP-UX platforms, if a referral fails because the server being referred to is not running, ensure that the environment variable LDAP_LOCK_REC has been set in your system environment. No specific value is required.

set LDAP_LOCK_REC=anyvalue

Creating credentials

Expand the Replication management category in the navigation area of the Web Administration Tool and click Manage credentials

1. Select the location that you want to use to store the credentials from the list of subtrees. The Web Administration Tool allows you to define credentials in two places:
   • cn=replication,cn=localhost, which keeps the credentials only on the current server.
   • Within the replicated subtree, in which case the credentials are replicated with the rest of the subtree.

   Placing credentials in cn=replication,cn=localhost is considered more secure. Credentials placed in the replicated subtree are created beneath the ibm-replicagroup=default entry for that subtree.

   Note:

   If no subtrees are displayed, go to Creating a replicated subtree (master server) for instructions about creating the subtree that you want to replicate.

2. Click Add.
3. Enter the name for the credentials you are creating, for example, mycreds.
4. Select the type of authentication method you want to use and click Next.
   • If you selected simple bind authentication:
     1. Enter the DN that the server uses to bind to the replica, for example, cn=any
     2. Enter the password uses when it binds to the replica, for example, secret.
     3. Enter the password again to confirm that there are no typographical errors.
     4. If you want, enter a brief description of the credentials.
     5. Click Finish.

     Note:

     You might want to record the credential's bind DN and password for future reference. You will need this password when you create the replica agreement.

   • If you selected Kerberos authentication:
     1. If you want, enter a brief description of the credentials. No other information is necessary. See Setting Kerberos for additional information.
     2. Click Finish.

     By default, the supplier uses its own service principal to bind with the consumer. For example, if the supplier is named master.our.org.com and the realm is SOME.REALM, the DN is ibm-Kn=ldap/master1.our.org.com@SOME.REALM. If there is more than one supplier, you must specify the principal and password to be used by all of the suppliers.

     On the server where you created the credentials:

     1. Expand Directory management and click on Manage entries.
     2. Select the subtree where you stored the credentials, for example cn=localhost and click Expand.
     3. Select cn=replication and click Expand.
     4. Select the kerberos credentials (ibm-replicationCredentialsKerberos) and click Edit attributes.
     5. Click the Other attributes tab.
     6. Enter the replicaBindDN, for example, ibm-kn=myprincipal@SOME.REALM.
     7. Enter the replicaCredentials. This is the KDC password used for myprincipal.

        Note:

        This principal and password should be the same as the ones you use to run kinit from the command line.

     On the replica

     1. Click Manage replication properties in the navigation area.
     2. Select a supplier from the Supplier information drop-down menu or enter the name of the replicated subtree for which you want to configure supplier credentials.
     3. Click Edit.
     4. Enter the replication bindDN. In this example, ibm-kn=myprincipal@SOME.REALM.
     5. Enter and confirm the Replication bind password. This is the KDC password used for myprincipal.

   • If you selected SSL with certificate authentication you do not need to provide any additional information, if you are using the server's certificate. If you choose to use a certificate other than the server's:
     1. Enter the key file name.
     2. Enter the key file password.
     3. Enter the key label.
     4. If you want, enter a brief description.
     5. Click Finish.

     See Secure Sockets Layer for additional information.

Creating a replica server

Note:

The server must be running to perform this task.

Expand the Replication management category in the navigation area and click Manage topology.

1. Select the subtree that you want to replicate and click Show topology.
2. Click the arrow next to the Replication topology selection to expand the list of supplier servers.
3. Select the supplier server and click Add replica.

On the Server tab of the Add replica window:

• Enter the host name and port number for the replica you are creating. The default port is 389 for non-SSL and 636 for SSL. These are required fields.
• Select whether to enable SSL communications.
• Enter the replica name or leave this field blank to use the host name.
• Enter the replica ID. If the server on which you are creating the replica is running, click Get replica ID to automatically prefill this field. This is a required field, if the server you are adding is going to be a peer or forwarding server. It is recommended for all IBM Directory Server Version 5.1 replica servers.
• Enter a description of the replica server.

On the Additional tab:

1. Specify the credentials that the replica uses to communicate with the master.

   Note:

   The Web Administration Tool allows you to define credentials in two places:

   • cn=replication,cn=localhost, which keeps the credentials only on the server that uses them
   • Within the replicated subtree, in which case the credentials are replicated with the rest of the subtree.

   Placing credentials in cn=replication,cn=localhost is considered more secure. Credentials placed in the replicated subtree are created beneath the ibm-replicagroup=default entry for that subtree.

   1. Click Select.
   2. Select the location for the credentials you want to use. Preferably this is cn=replication,cn=localhost.
   3. Click Show credentials.
   4. Expand the list of credentials and select the one you want to use.
   5. Click OK.

   See Creating credentials for additional information on agreement credentials.

2. Specify a replication schedule from the drop-down list or click Add to create one. See Creating replication schedules
3. From the list of supplier capabilities, you can deselect any capabilities that you do not want replicated to the consumer.

   If your network has a mix of servers at different releases, capabilities are available on later releases that are not available on earlier releases. Some capabilities, like filter ACLs and password policy, make use of operational attributes that are replicated with other changes. In most cases, if these features are used, you want all servers to support them. If all of the servers do not support the capability, you do not want to use it. For example, you would not want different ACLs in effect on each server. However, there might be cases where you might want to use a capability on the servers that support it, and not have changes related to the capability replicated to servers that do not support the capability. In such cases, you can use the capabilities list to mark certain capabilities to not be replicated.

4. Click OK to create the replica.

Copying data to the replica

After creating the replica, you must now export the topology from the master to the replica. This is a manual procedure.

On the master server create an LDIF file for the data. To copy all the data contained on the master server, issue the command:

db2ldif -o <masterfile.ldif>

If you want to copy just the data from a single subtree the command is:

db2ldif -o <masterfile.ldif> -s <subtreeDN>

On the machine where you are creating the replica:

1. Ensure that the suffixes used by the master are defined in the ibmslapd.conf file.
2. Stop the replica server.
3. Copy the <masterfile.ldif> to the replica and issue the command:

   ldif2db -r no -i <masterfile.ldif>
   

   The replication agreements, schedules, credentials (if stored in the replicated subtree) and entry data are loaded on the replica.

4. Start the server.

Adding the supplier information to the replica

You need to change the replica's configuration to identify who is authorized to replicate changes to it, and add a referral to a master.

On the machine where you are creating the replica:

1. Click Manage replication properties in the navigation area.
2. Click Add.
3. Select a supplier from the Replicated subtree drop-down menu or enter the name of the replicated subtree for which you want to configure supplier credentials. If you are editing supplier credentials, this field is not editable.
4. Enter the replication bindDN. In this example, cn=any.

   Note:

   You can use either of these two options, depending on your situation.

   • Set the replication bind DN (and password) and a default referral for all subtrees replicated to a server using the 'default credentials and referral'. This might be used when all subtrees are replicated from the same supplier.
   • Set the replication bind DN and password independently for each replicated subtree by adding supplier information for each subtree. This might be used when each subtree has a different supplier (that is, a different master server for each subtree).

5. Depending on the type of credential, enter and confirm the credential password. (You previously recorded this for future use.)
   • Simple Bind - Specify the DN and password
   • Kerberos - If the credentials on the supplier do not identify the principal and password, that is, the server's own service principal is to be used, then the bind DN is ibmkn=ldap/<yourservername@yourrealm>. If the credentials has a principal name such as <myprincipal@myrealm>, use that as the DN. In either case a password in not needed.
   • SSL w/ EXTERNAL bind - Specify the subject DN for the certificate and no password

   See Creating credentials.

6. Click OK.
7. You must restart the replica for the changes to take effect.

See Modifying replication properties for additional information.

The replica is in a suspended state and no replication is occurring. After you have finished setting up your replication topology, you must click Manage queues, select the replica and click Suspend/resume to start replication. See Managing queues for more detailed information. The replica now receives updates from the master.

Setting up a forwarding server

If you have set up a replication topology (see Creating a replicated subtree (master server)) with a master (server1) and a replica (server2), you can change the role of server2 to that of a forwarding server. To do this you need to create a new replica (server3) under server2.

1. Connect Web Administration to the master (server1)
2. Expand the Replication management category in the navigation area and click Manage topology.
3. Select the subtree that you want to replicate and click Show topology.
4. Click the arrow next to the Replication topology selection to expand the list of supplier servers.
5. Click the arrow next to the server1 selection to expand the list of servers.
6. Select server2 and click Add replica.

7. On the Server tab of the Add replica window:

   • Enter the host name and port number for the replica (server3) you are creating. The default port is 389 for non-SSL and 636 for SSL. These are required fields.
   • Select whether to enable SSL communications.
   • Enter the replica name or leave this field blank to use the host name.
   • Enter the replica ID. If the server on which you are creating the replica is running, click Get replica ID to automatically prefill this field. This is a required field, if the server you are adding is going to be a peer or forwarding server. It is recommended for all IBM Directory Server Version 5.1 replica servers.
   • Enter a description of the replica server.

   On the Additional tab:

   1. Specify the credentials that the replica uses to communicate with the master.

      Note:

      The Web Administration Tool allows you to define credentials in two places:

      • cn=replication,cn=localhost, which keeps the credentials only on the server that uses them.
      • Within the replicated subtree, in which case the credentials are replicated with the rest of the subtree.

      Placing credentials in cn=replication,cn=localhost is considered more secure. Credentials placed in the replicated subtree are created beneath the ibm-replicagroup=default entry for that subtree.

      1. Click Select.
      2. Select the location for the credentials you want to use. Preferably this is cn=replication,cn=localhost.
      3. Click Show credentials.
      4. Expand the list of credentials and select the one you want to use.
      5. Click OK.

      See Creating credentials for additional information on agreement credentials.

   2. Specify a replication schedule from the drop-down list or click Add to create one. See Creating replication schedules.
   3. From the list of supplier capabilities, you can deselect any capabilities that you do not want replicated to the consumer.

      If your network has a mix of servers at different releases, capabilities are available on later releases that are not available on earlier releases. Some capabilities, like filter ACLs and password policy, make use of operational attributes that are replicated with other changes. In most cases, if these features are used, you want all servers to support them. If all of the servers do not support the capability, you do not want to use it. For example, you would not want different ACLs in effect on each server. However, there might be cases where you might want to use a capability on the servers that support it, and not have changes related to the capability replicated to servers that do not support the capability. In such cases, you can use the capabilities list to mark certain capabilities to not be replicated.

   4. Click OK to create the replica.
8. Copy data from server2 to the new replica server3. See Copying data to the replica for information on how to do that.
9. Add the supplier agreement to server3 that makes server2 a supplier to server 3 and server 3 a consumer to server2. See Adding the supplier information to the replica for information on how to do this.

Your topology in now:

• server1 (master)
  • server2 (forwarder)
    • server3 (replica)

Managing topologies

Topologies are specific to the replicated subtrees.

Viewing the topology

Note:

The server must be running to perform this task.

Expand the Replication management category in the navigation area and click Manage topology.

1. Select the subtree that you want to view and click Show topology.

The topology is displayed in the Replication topology list. Expand the topologies by clicking the blue triangles. From this list you can:

• Add a replica.
• Edit information on an existing replica.
• Change to a different supplier server for the replica or promote the replica to a master server
• Delete a replica.

Adding a replica

See Creating a replica server.

Editing a replica

You can change the following information for the replica:

On the Server tab you can only change

• Hostname
• Port
• Enable SSL
• Description

On the Additional tab you can change:

• Credentials - see Creating credentials.
• Replication schedules - see Creating replication schedules.
• Change the capabilities replicated to the consumer replica. From the list of supplier capabilities, you can deselect any capabilities that you do not want replicated to the consumer.
• When you are finished, click OK.

Moving or promoting a server

1. Select the subtree you want to promote or move and Click Move.
2. Select the server that you want to move the replica to, or select Replication topology to promote the replica to a master. Click Move.
3. In some cases the Select credentials panel will pop up asking for a credential which is located in a place other than cn=replication,cn=localhost. In such situations you must provide a credential object which is located in a place other than cn=replication,cn=localhost. Select the credentials the subtree is going to use form the existing sets of credentials or create new credentials. See Creating credentials.
4. Click OK.

The change in the topology tree reflects the moving of the server.

See Peer to peer replication for more information.

Replicating a subtree

Note:

The server must be running to perform this task.

Expand the Replication management category in the navigation area and click Manage topology.

• Click Add subtree.
• Enter the DN of the subtree that you want to replicate or click Browse to expand the entries to select the entry that is to be the root of the subtree.
• Enter the master server referral URL. This must be in the form of an LDAP URL, for example:

  ldap://<myservername>.<mylocation>.<mycompany>.com
  

• Click OK.
• The new server is displayed on the Manage topology panel under the heading Replicated subtrees.

Note:

On the Linux, Solaris, and HP-UX platforms, if a referral fails, ensure that the environment variable LDAP_LOCK_REC has been set in your system environment. No specific value is required.

set LDAP_LOCK_REC=anyvalue

Editing a subtree

Use this option to change the URL of the master server that this subtree and its replicas send updates to. You need do this if you change the port number or host name of the master server, change the master to a different server

1. Select the subtree you want to edit.
2. Click Edit subtree.
3. Enter the master server referral URL. This must be in the form of an LDAP URL, for example:

   ldap://<mynewservername>.<mylocation>.<mycompany>.com
   

Depending on the role being played by the server on this subtree (whether it is a master, replica or forwarding), different labels and buttons appear on the panel.

• When the subtree's role is replica, a label indicating that the server acts as a replica or forwarder is displayed along with the button Make server a master. If this button is clicked then the server which the Web Administration Tool is connected to becomes a master.
• When the subtree is configured for replication only by adding the auxiliary class (no default group and subentry present), then the label This subtree is not replicated is displayed along with the button Replicate subtree. If this button is clicked, the default group and the subentry is added so that the server with which the Web Administration Tool is connected to becomes a master.
• If no subentries for the master servers are found,, the label No master server is defined for this subtree is displayed along with the button titled Make server a master. If this button is clicked, the missing subentry is added so that the server with which the Web Administration Tool is connected to becomes a master.

Removing a subtree

1. Select the subtree you want to remove
2. Click Delete subtree.
3. When asked to confirm the deletion, click OK.

The subtree is removed from the Replicated subtree list.

Note:

This operation succeeds only if the ibm-replicaGroup=default is entry is empty.

Quiescing the subtree

This function is useful when you want to perform maintenance on or make changes to the topology. It minimizes the number of updates that can be made to the server. A quiesced server does not accept client requests. It accepts requests only from an administrator using the Server Administration control.

This function is Boolean.

1. Click Quiesce/Unquiesce to quiesce the subtree.
2. When asked to confirm the action, click OK.
3. Click Quiesce/Unquiesce to unquiesce the subtree.
4. When asked to confirm the action, click OK.

Editing access control lists

Replication information (replica subentries, replication agreements, schedules, possibly credentials) are stored under a special object, ibm-replicagroup=default. The ibm-replicagroup object is located immediately beneath the root entry of the replicated subtree. By default, this subtree inherits ACL from the root entry of the replicated subtree. This ACL might not be appropriate for controlling access to replication information.

Required authorities:

• Control replication - You must have write access to the ibm-replicagroup=default object (or be the owner/administrator).
• Cascading control replication - You must have write access to the ibm-replicagroup=default object (or be the owner/administrator).
• Control queue - You must have write access to the replication agreement.

To view ACL properties using the Web Administration Tool utility and to work with ACLs, see Working with Access Control Lists.

See Access Control Lists for additional information.

Modifying replication properties

Expand the Replication management category in the navigation area and click Manage replication properties.

On this panel you can:

• Change the maximum number of pending changes to return from replication status queries. The default is 200.
• Add, edit, or delete supplier information.

Adding supplier information

1. Click Add.
2. Select a supplier from the drop-down menu or enter the name of the replicated subtree that you want to add as a supplier .
3. Enter the replication bind DN for the credentials.

   Note:

   You can use either of these two options, depending on your situation.

   • Set the replication bind DN (and password) and a default referral for all subtrees replicated to a server using the 'default credentials and referral'. This might be used when all subtrees are replicated from the same supplier.
   • Set the replication bind DN and password independently for each replicated subtree by adding supplier information for each subtree. This might be used when each subtree has a different supplier (that is, a different master server for each subtree).

4. Depending on the type of credential, enter and confirm the credential password. (You previously recorded this for future use.)
   • Simple Bind - specify the DN and password
   • Kerberos - specify a pseudo DN of the form 'ibm-kn=LDAP-service-name@realm' without a password
   • SSL w/ EXTERNAL bind - specify the subject DN for the certificate and no password
   See Creating credentials.
5. Click OK.

The subtree of the supplier is added to the Supplier information list.

Editing supplier information

1. Select the supplier subtree that you want to edit.
2. Click Edit.
3. If you are editing Default credentials and referral, which is used to create the cn=Master Server entry under cn=configuration, enter the URL of the server from which the client wants to receive replica updates in the Default supplier's LDAP URL field. This needs to be a valid LDAP URL (ldap://). Otherwise, skip to step 4.
4. Enter the replication bind DN for the new credentials you want to use.
5. Enter and confirm the credential password.
6. Click OK.

Removing supplier information

1. Select the supplier subtree that you want to remove.
2. Click Delete.
3. When asked to confirm the deletion, click OK.

The subtree is removed from the Supplier information list.

Creating replication schedules

You can optionally define replication schedules to schedule replication for particular times, or to not replicate during certain times. If you do not use a schedule, the server schedules replication whenever a change is made. This is equivalent to specifying a schedule with immediate replication starting at 12:00 AM on all days.

Expand the Replication management category in the navigation area and click Manage schedules.

On the Weekly schedule tab, select the subtree for which you want to create the schedule and click Show schedules. If any schedules exist, they are displayed in the Weekly schedules box. To create or add a new schedule:

1. Click Add.
2. Enter a name for the schedule. For example schedule1.
3. For each day, Sunday through Saturday, the daily schedule is specified as None. This means that no replication update events are scheduled. The last replication event, if any, is still in effect. Because this is a new replica, there are no prior replication events, therefore, the schedule defaults to immediate replication.
4. You can select a day and click Add a daily schedule to create a daily replication schedule for it. If you create a daily schedule it becomes the default schedule for each day of the week. You can:
   • Keep the daily schedule as the default for each day or select a specific day and change the schedule back to none. Remember that the last replication event that occurred is still in effect for a day that has no replication events scheduled.
   • Modify the daily schedule by selecting a day and clicking Edit a daily schedule. Remember changes to a daily schedule affect all days using that schedule, not just the day you selected.
   • Create a different daily schedule by selecting a day and clicking Add a daily schedule. After you have created this schedule it is added to the Daily schedule drop-down menu. You must select this schedule for each day that you want the schedule to be used.

   See Creating a daily schedule for more information on setting up daily schedules.

5. When you are finished, click OK.

Creating a daily schedule

Expand the Replication management category in the navigation area and click Manage schedules.

On the Daily schedule tab, select the subtree for which you want to create the schedule and click Show schedules. If any schedules exist, they are displayed in the Daily schedules box. To create or add a new schedule:

1. Click Add.
2. Enter a name for the schedule. For example monday1.
3. Select the time zone setting, either UTC or local.
4. Select a replication type from the drop-down menu:

   Immediate

   Performs any pending entry updates since the last replication event and then updates entries continuously until the next scheduled update event is reached.

   Once

   Performs all pending updates prior to the starting time. Any updates made after the start time wait until the next scheduled replication event.

5. Select a start time for the replication event.
6. Click Add. The replication event type and time are displayed.
7. Add or remove events to complete your schedule. The list of events is refreshed in chronological order.
8. When you are finished, click OK.

For example:

Table 10.

In this schedule, the first replication event occurs at midnight and updates any pending changes prior to that time. Replication updates continue to be made as they occur until 10:00 AM. Updates made between 10:00 AM and 2:00 PM wait until 2:00 PM to be replicated. Any updates made between 2:00 PM and 4:00 PM wait the replication event scheduled at 4:00 PM, afterwards replication updates continue until the next scheduled replication event at 8:00 PM. Any updates made after 8:00 PM wait until the next scheduled replication event.

Note:

If replication events are scheduled too closely together, a replication event might be missed if the updates from the previous event are still in progress when the next event is scheduled.

Managing queues

This task allows you to monitor status of replication for each replication agreement (queue) used by this server.

Expand the Replication management category in the navigation area and click Manage queues.

Select the replica for which you want to manage the queue.

• Depending on the status of the replica, you can click Suspend/resume to stop or start replication.
• Click Force replication to replicate all the pending changes regardless of when the next replication is scheduled.
• Click Queue details, for more complete information about the replica's queue. You can also manage the queue from this selection.
• Click Refresh to update the queues and clear server messages.

Queue details

If you clicked Queue details, three tabs are displayed:

• Status
• Last attempted details
• Pending changes

The Status tab displays the replica name, its subtree, its status, and a record of replication times. From this panel you can suspend or resume replication by clicking Resume. Click Refresh to update the queue information.

The Last attempted details tab gives information about the last update attempt. If an entry is not able to be loaded press Skip blocking entry to continue replication with the next pending entry. Click Refresh to update the queue information.

The Pending changes tab shows all the pending changes to the replica. If replication is blocked you can delete all the pending changes by clicking Skip all. Click Refresh to update the list of pending changes to reflect any new update or updates that have been processed.

Note:

If you choose to skip blocking changes, you must ensure that the consumer server is eventually updated. See ldapdiff for more information.

Peer to peer replication

Peer replication is a replication topology in which multiple servers are masters. However, unlike a multi-master environment, no conflict resolution is done among peer servers. LDAP servers accept the updates provided by peer servers, and update their own copies of the data. No consideration is given for the order the updates are received, or whether multiple updates conflict.

Use peer replication only in environments where the update vectors are well known. Updates to particular objects within the directory must be done only by one peer server. This is intended to prevent the scenario of one server deleting an object, followed by another server modifying the object. This scenario creates the possibility of a peer server receiving a delete command followed by a modify command; which creates a conflict.

Creating a complex replication topology

Use this high level overview as a guide for setting up a complex replication topology.

1. Start or place all of the potential peer masters and replicas-to-be in Configuration only mode.
2. Start the 'first' master and configure it as a master for the context.
3. Load the data for the subtree to be replicated on the 'first' master, if the data is not already loaded.
4. Select the subtree to be replicated.
5. Add all of the potential peer masters as replicas of the 'first' master.
6. Add all of the other replicas.
7. Move the other peer masters to promote them.
8. Add replica agreements for the replicas to each of the peer masters.

   Note:

   If the credentials are to be created in cn=replication,cn=localhost, the credentials must be created on each server after they are restarted. Replication by the peers fails until the credential objects are created.

9. Add replica agreements for the other masters to each of the peer masters. The 'first' master already has that information.
10. Quiesce the replicated subtree.
11. Use Queue management to skip all for each queue.
12. Export the data for the replicated subtree from the 'first' master.
13. Unquiesce the subtree.
14. Import the data for the replicated subtree on to each replica and peer master.
15. Manage the replication properties on each replica and peer master to set the credentials to be used by suppliers.
16. Restart the replicas and peer masters as soon as each is ready.

Creating a peer server

Using the forwarding topology created in Setting up a forwarding server, you can promote a server to be a peer. In this example you are going to promote the replica (server3) to be a peer to the master server (server1).

1. Connect Web Administration to the master (server1).
2. Expand the Replication management category in the navigation area and click Manage topology.
3. Select the subtree that you want to replicate and click Show topology.
4. Click the arrow next to the Replication topology selection to expand the list of supplier servers.
5. Click the arrow next to the server1 selection to expand the list of servers.
6. Click the arrow next to the server2 selection to expand the list of servers.

   Note:

   The server you want to move must be a leaf replica with no subordinate replicas.

7. Select server3 and click Move.
8. Select Replication topology to promote the replica to a master. Click Move.
9. In some cases the Select credentials panel will pop up asking for a credential which is located in a place other than cn=replication,cn=localhost. In such situations you must provide a credential object which is located in a place other than cn=replication,cn=localhost. Select the credentials the subtree is going to use form the existing sets of credentials or create new credentials. See Creating credentials.
10. Click OK. The topology is now:
    • server1 (master-peer)
      • server2 (replica)
      • server3 (replica)
    • server3 (master-peer)

    As it can be seen from the topology, an agreement between server2 and server3 which was exisitng previously was deleted. An agreement between server1 and server3 is created (required for a peer master) A subentry corresponding to the machine server3 is also created. To complete the setting up of a peer master, an agreement from server3 to server1 must be added.

11. Select server3 and click Add replica.
12. Make server1 a replica for server3. See Creating a replica server. On the Additional tab, use the credential object which is located inside the default group entry of the replicated subtree.

    Note:

    For peer replication to work correctly ensure that the credentials you uses for each agreement have the same DN and password. This DN cannot be the same as the AdminDN.

13. Because this is a peer environment you must also make server2 a replica for server3. See Creating a replica server. Now server2 can be updated by either server1 or server3.

The peer topology is now:

• server1 (master-peer)
  • server2 (replica)
  • server3 (replica)
• server3 (master-peer)
  • server1 (replica)
  • server2 (replica)

If you wanted to promote server2 so that the topology contains three master-peer servers, use the same procedure that was used to promote server3. Agreements must be made among all peer servers. The three-peer topology is now:

• server1 (master-peer)
  • server2 (replica)
  • server3 (replica)
• server3 (master-peer)
  • server1 (replica)
  • server2 (replica)
• server2 (master-peer)
  • server1 (replica)
  • server3 (replica)

Demoting a master

To change the role of a server from a master to a replica do the following:

1. Connect the Web Administration Tool to the server that you want to demote.
2. Click Manage topology.
3. Select the subtree and click Show topology.
4. Delete all the agreements for the server you want to demote.
5. Select the server you are demoting and click Move.
6. Select the server under which you are going to place the demoted server and click Move.
7. Just as you would for a new replica, create new supplier agreements between the demoted server and its supplier. See Creating a replica server for instructions.

Command line replication

The following are examples of setting up replication using the command line utilities and an LDIF file. The scenarios are of increasing complexity:

• One master and one replica
• One master, one forwarder, and one replica
• Two peer/masters, two forwarders, and four replicas.

Each of these scenarios assume that you are creating new replicated subtrees.

Note:

dn: o=ibm,c=us
objectclass: organization
objectclass: ibm-replicationContext
 

is the subtree you want to create. If this entry already exists, then modify it to add objclass=ibm-replicationContext instead of adding the entire entry.

Setting up a single master and replica

To create a replica for a subtree, you need to create a replica agreement between the master and the replica, see Replication agreements. This agreement needs to be loaded on both the master and the replica.

The relationship between the two servers is that the master is a supplier to the replica and the replica is a consumer of the master.

To create the master (master) and replica (replica1) for the subtree o=ibm,c=us:

1. At the machine where the master is located, create a file to contain the agreement information, for example, myreplicainfofile, where myreplicainfofile contains:

   Note:

   Replace all occurrences of <master-uuid> in the following files with the value of the ibm-slapdServerId attribute from the master server's cn=Configuration entry. This value is generated by the server the first time it is started. You can find it either by performing an ldapsearch of the cn=Configuration entry or using the grep command on the ibmslapd.conf file, if you have a UNIX-based system. Similarly, all occurrences of the <replica1-uuid> must be replaced with the value of the ibm-slapdServerId attribute from the replica server's cn=Configuration entry.

   ###Replication Context  - needs to be on all suppliers and consumers
   dn: cn=replication,cn=localhost
   objectclass: container
    
   dn: o=ibm,c=us
   objectclass: organization
   objectclass: ibm-replicationContext
    
    
   ###Copy the following to servers at v5.1 or later.
    
   ###Replica Group
   dn: ibm-replicaGroup=default, o=IBM, c=US
   objectclass: top
   objectclass: ibm-replicaGroup
   ibm-replicaGroup: default
    
   ###Bind Credentials/method to replica server - replication agreement 
   ###points to this.
   dn: cn=replica1 BindCredentials,cn=replication,cn=localhost
   objectclass: ibm-replicationCredentialsSimple
   cn: replica1 BindCredentials
   replicaBindDN: cn=master
   replicaCredentials: master
   description: Bindmethod of master to replica1
    
   ###Replica SubEntry
   dn: ibm-replicaServerId=<master-uuid>,ibm-replicaGroup=default,o=IBM, c=US
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <master-uuid>
   ibm-replicationServerIsMaster: true
   cn: master
   description: master server
    
   ###Replication Agreement to Replica Server
   dn: cn=replica1,ibm-replicaServerId=<master-uuid>,
       ibm-replicaGroup=default,o=IBM,c=US
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica1
   ibm-replicaConsumerId: <replica1-uuid>
   ibm-replicaUrl: ldap://<replicahostname:replicaport>
   ibm-replicaCredentialsDN: cn=replica1 BindCredentials,cn=replication,
                             cn=localhost
   description: replica server number one
    
   

2. Stop the master, if it is not already stopped.
3. Issue the command:

   ldif2db -r no -i <myreplicainfofile>
   

4. Issue the command:

   db2ldif -o <masterfile.ldif>
   

   See db2ldif utility for more information.

5. Copy <masterfile.ldif> to the machine where replica1 is located.
6. Stop the replica if it is running.
7. You must configure replica1 to be a replica server. Use an editor to add the following stanza to the ibmslapd.conf file on replica1:

   dn: cn=Master Server, cn=configuration
   objectclass: ibm-slapdReplication
   cn: Master Server
   ibm-slapdMasterDN: <cn=masterbndn>
   ibm-slapdMasterPW: <masterbnpw>
   ibm-slapdMasterReferral: ldap://<masterhostname>:<masterport>/
    
   

8. Save the ibmslapd.conf file.
9. Issue the following command:

   ldif2db -r no -i <masterfile.ldif>
   

10. Start master and replica1.

Note:

If you are copying a subtree to a v4.1 or earlier server, you must not copy the ibm-replicagroup=default subtree and you must remove the ibm-replicationcontext auxiliary class, because neither of these are supported by the 4.1 schema.

Setting up a single master, a forwarder, and a replica

This procedure is similar to the one for a single master and replica, except that the entire topology must be added to each of the servers and the content of the agreement information file is more complex. The file now includes information for the forwarding server and supplier-consumer information.

The supplier-consumer relationship for this scenario is:

• The master is a supplier to the forwarder.
• The forwarder has two roles:
  1. A consumer of the master
  2. A supplier to the replica
• The replica is a consumer of the forwarder.

To create the master (master), a forwarder (forwarder1), and replica (replica1) for the subtree o=ibm,c=us:

1. At the machine where the master server is located, create a file to contain the agreement information, for example myreplicainfofile where myreplicainfofile contains:

   Note:

   Replace all occurrences of <master-uuid> in the following files with the value of the ibm-slapdServerId attribute from the master server's cn=Configuration entry. This value is generated by the server the first time it is started. You can find it either by performing an ldapsearch of the cn=Configuration entry or using the grep command on the ibmslapd.conf file, if you have a UNIX-based system. Similarly, all occurrences of the <forwarder1-uuid> and the <replica1-uuid> must be replaced with the value of the ibm-slapdServerId attribute from the respective server's cn=Configuration entry.

   dn: cn=replication,cn=localhost
   objectclass: container
    
   dn: o=ibm,c=us
   objectclass: organization
   objectclass: ibm-replicationContext
    
   dn: ibm-replicaGroup=default, o=ibm,c=us 	
   objectclass: top
   objectclass: ibm-replicaGroup
   ibm-replicaGroup: default
    
   dn: cn=forwarder1 BindCredentials,cn=replication,cn=localhost
   objectclass: ibm-replicationCredentialsSimple                            	
          #or ibm-replicationCredentialsExternal or 
          #ibm-replicationCredentialsKerberos
   cn: forwarder1 BindCredentials
   replicaBindDN: <cn=forw1bnddn>
   replicaCredentials: <forw1bndpw>
   cn:forwarder1 BindCredentials
   description: Bindmethod of master to forwarder1
    
   dn: cn=replica1 BindCredentials,cn=replication,cn=localhost
   objectclass: ibm-replicationCredentialsSimple 
   cn: replica1 BindCredentials
   replicaBindDN: <cn=rep1bnddn>
   replicaCredentials: <rep1bndpw>
   description: Bindmethod of forwarder1 to replica1
    
   dn: ibm-replicaServerId=<master-uuid>,ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <master-uuid>        #whatever the id is in the config
   ibm-replicationServerIsMaster: true		#true if master, false if forwarder
   cn: master
   description: master ibm-replicaSubentry
    
   dn: ibm-replicaServerId=<forwarder1-uuid>,ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <forwarder1-uuid>ibm-replicationServerIsMaster: false    			
   cn: forwarder1
   description: forwarder1 ibm-replicaSubentry
    
   dn: cn=forwarder1,ibm-replicaServerId=<master-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us	
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder1
   ibm-replicaConsumerId: <forwarder1-uuid>
   ibm-replicaUrl: ldap://<forwarder1hostname:forwarder1port>
   ibm-replicaCredentialsDN: cn=forwarder1 BindCredentials,cn=replication,
                             cn=localhost
   description: master1 to forwarder1 agreement
    
   dn: cn=replica1,ibm-replicaServerId=<forwarder1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica1
   ibm-replicaConsumerId: <replica1-uuid>-uuid
   ibm-replicaUrl: ldap://<replica1hostname:replica1port>
   ibm-replicaCredentialsDN: cn=replica1 BindCredentials,cn=replication,
                             cn=localhost
   description: forwarder1 to replica1 agreement
    
    
   

2. Stop the master, if it is not already stopped.
3. Issue the command:

   ldif2db -r no -i  <myreplicainfofile>
   

4. Issue the command:

   db2ldif -o <masterfile.ldif>
   

   See db2ldif utility for more information.

5. Copy <masterfile.ldif> to the machine where forwarder1 is located.
6. Stop forwarder1 if it is running.
7. You must configure forwarder1 to be a forwarding server. Use an editor to add the following stanza to the ibmslapd.conf file on forwarder1:

   dn: cn=Master Server, cn=configuration
   objectclass: ibm-slapdReplication
   cn: Master Server
   ibm-slapdMasterDN: <cn=masterbnddn>
   ibm-slapdMasterPW: <masterbndp>w
   ibm-slapdMasterReferral: ldap://masterhostname:masterport/         
             #referral to master when trying to add to consumer.  
             #Referral can also be added to replicaContext, which would be 
             #checked first for a valid server.
    
   

8. Save the ibmslapd.conf file.
9. Copy <masterfile.ldif> to the machine where replica1 is located.
10. Stop replica1 if it is running.
11. You must configure replica1 to be a replica server. Use an editor to add the following stanza to the ibmslapd.conf file on replica1:

    dn: cn=Master Server, cn=configuration
    objectclass: ibm-slapdReplication
    cn: Master Server
    ibm-slapdMasterDN: <cn=forw1bndn>
    ibm-slapdMasterPW: <forw1bnpw>
    ibm-slapdMasterReferral: ldap://forw1hostname:forw1port/
    

12. Save the ibmslapd.conf file.
13. At the machines where forwarder1 and replica1 are located, issue the following command:

    ldif2db -r no -i <masterfile.ldif>
    

14. Start master, forwarder1 and replica1.

Setting up a complex topology

In this example the topology is more complex. It includes two peer-masters (peer1 and peer2), two forwarders (forwarder1 and forwarder2) and four replicas (replica1, replica2, replica3, and replica4). The relationship among the servers is as follows:

• peer1 and peer2 are peer-master servers. That means that while they receive updates from each other, they only replicate entries received from clients. While both masters have the same entry content, only the server that has received the client request replicates the entry. Both masters are suppliers and consumers to each other and suppliers to the forwarding servers.
• forwarder1 and forwarder 2 have two roles. They are both consumers of peer1 and peer2 and suppliers to their respective replicas. They do not perform any client updates. They pass replicated updates to their consumers. In this scenario
  • forwarder1 is a supplier to replica1 and replica2
  • forwarder2 is a supplier to replica3 and replica4

  There is no interaction between forwarder1 and forwarder2.

• replica 1 and replica 2 are consumers of forwarder1 and replica3 and replica4 are consumers of forwarder2.

To create the peer-masters (peer1 and peer2), the forwarders (forwarder1 and forwarder2), and the replicas (replica1, replica2, replica3, and replica4) for the subtree o=ibm,c=us:

1. Stop peer1 and peer2.
2. You must configure peer1 and peer2 to be peer servers. Use an editor to add the following stanza to the ibmslapd.conf files on peer1 and peer2:

   dn: cn=MasterServer, cn=configuration
   objectclass: ibm-slapdReplication
   cn: Master Server
   ibm-slapdMasterDN: cn=master
   ibm-slapdMasterPW: master
    
   

   Note:

   It is critical that these stanzas be exactly the same on both servers because this example uses a credentials object that is shared on all the servers. However, there is no requirement that each server be configured with the same replication bind DN.

3. Save the ibmslapd.conf files.
4. At the machine where the master server, peer1, is located, create a file to contain the agreement information, for example mycredentialsfile where mycredentialsfile contains:

   dn: cn=simple,cn=replication,cn=localhost
   objectclass: ibm-replicationCredentialsSimple
   cn: peer2 BindCredentials
   replicaBindDN: cn=master
   replicaCredentials: master
   description: Bindmethod for topology
    
    
    
    
   

5. Issue the command:

   ldif2db -r no -i  <mycredentialsfile>
   

6. Copy <mycredentialsfile> to the machines where peer2, forwarder1, and forwarder2 are located and issue the command:

   ldif2db -r no -i  <mycredentialsfile>
   

   on each machine.

7. At the machine where peer1 is located create a file <mytopologyfile> where <mytopologyfile> includes:

   Note:

   Replace all occurrences of <master-uuid> in the following files with the value of the ibm-slapdServerId attribute from the master server's cn=Configuration entry. This value is generated by the server the first time it is started. You can find it either by performing an ldapsearch of the cn=Configuration entry or using the grep command on the ibmslapd.conf file, if you have a UNIX-based system. Similarly, all occurrences of the <peerx-uuid>, <forwarderx-uuid> and the <replicax-uuid> (where x represents a number) must be replaced with the value of the ibm-slapdServerId attribute from the respective server's cn=Configuration entry.

   dn: cn=replication,cn=localhost
   objectclass: container
    
   dn: o=ibm,c=us
   o: ibm
   objectclass: top
   objectclass: organization
   objectclass: ibm-replicationContext
    
   objectclass: ibm-replicaGroup
   ibm-replicaGroup: default
    
   dn: ibm-replicaGroup=default, o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaGroup
   ibm-replicaGroup: default
    
   dn: ibm-replicaServerId=<peer1-uuid>,ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <peer1-uuid>
   ibm-replicationServerIsMaster: true
   cn: peer1
   description: peer1 server
    
   dn: ibm-replicaServerId=<peer2-uuid>,ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <peer2-uuid>
   ibm-replicationServerIsMaster: true
   cn: peer2
   description: peer2 server
    
   dn: ibm-replicaServerId=<forwarder1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <forwarder1-uuid>ibm-replicationServerIsMaster: false
   cn: forwarder1
   description: forwarder server number one
    
   dn: ibm-replicaServerId=<forwarder2-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <forwarder2-uuid>
   ibm-replicationServerIsMaster: false
   cn: forwarder2
   description: forwarder server number two
    
   #peer1 to peer2 agreement
   dn: cn=peer2,ibm-replicaServerId=<peer1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: peer2
   ibm-replicaConsumerId: <peer2-uuid>
   ibm-replicaUrl: ldap://<peer2hostname:peer2port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: peer2 server
    
   #peer1 to forwarder1 agreement
   dn: cn=forwarder1,ibm-replicaServerId=<peer1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder1
   ibm-replicaConsumerId: <forwarder1-uuid>
   ibm-replicaUrl: ldap://<forwarder1hostname:forwarder1port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: forwarder server one
    
   #peer1 to forwarder2 agreement
   dn: cn=forwarder2,ibm-replicaServerId=<peer1-uuid>
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder2
   ibm-replicaConsumerId: <forwarder2-uuid>
   ibm-replicaUrl: ldap://<forwarder2hostname:forwarder2port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: forwarder server two
    
   #peer2 to peer1 agreement
   dn: cn=peer1,ibm-replicaServerId=<peer2-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder1
   ibm-replicaConsumerId: <peer1-uuid>
   ibm-replicaUrl: ldap://<peer1hostname:peer1port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: peer server one
    
   #peer2 to forwarder1 agreement
   dn: cn=forwarder1,ibm-replicaServerId=<peer2-uuid>
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder1
   ibm-replicaConsumerId: forwarder1-uid
   ibm-replicaUrl: ldap://<forwarder1hostname:forwarder1port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: forwarder server one
    
   #peer2 to forwarder2 agreement
   dn: cn=forwarder2,ibm-replicaServerId=<peer2-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: forwarder2
   ibm-replicaConsumerId: <forwarder2-uuid>
   ibm-replicaUrl: ldap://$<forwarder2hostname:forwarder2port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: forwarder server two
    
   #forwarder1 to replica1 agreement
   dn: cn=replica1,ibm-replicaServerId=<forwarder1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica1
   ibm-replicaConsumerId: <replica1-uuid>
   ibm-replicaUrl: ldap://<replica1hostname:replica1port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: replica server number one
    
   #forwarder1 to replica2 agreement
   dn: cn=replica2,ibm-replicaServerId=<forwarder1-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica2
   ibm-replicaConsumerId: <replica2-uuid>
   ibm-replicaUrl: ldap://<replica2hostname:replica2port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: replica server number two
    
   #forwarder2 to replica3 agreement
   dn: cn=replica3,ibm-replicaServerId=<forwarder2-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica3
   ibm-replicaConsumerId: <replica3-uuid>
   ibm-replicaUrl: ldap://<replica3hostname:replica3port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: replica server number three
    
   #forwarder2 to replica4 agreement
   dn: cn=replica4,ibm-replicaServerId=<forwarder2-uuid>,
       ibm-replicaGroup=default,o=ibm,c=us
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica4
   ibm-replicaConsumerId: <replica4-uuid>
   ibm-replicaUrl: ldap://<replica4hostname:replica4port>
   ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=localhost
   description: replica server number four
   

8. Issue the command:

   ldif2db -r no -i  <mytopologyfile>
   

9. At this point you might want to load additional data for you subtree.
10. When you have finished loading the data, issue the command:

    db2ldif  -s"o=ibm,c=us" -o <mymasterfile.ldif>
    

    See db2ldif utility for more information.

11. Copy <masterfile.ldif> to the machine where peer2 is located.
12. At the machine where peer2 is located, issue the following command:

    ldif2db -r no -i <masterfile.ldif>
    

13. Ensure that forwarder1 and forwarder2 are stopped.
14. You must configure forwarder1 and forwarder2 to be forwarding servers. Use an editor to add the following stanza to the ibmslapd.conf files on forwarder1 and forwarder2:

    dn: cn=MasterServer, cn=configuration
    cn: Master Server
    ibm-slapdMasterDN: cn=master
    ibm-slapdMasterPW: master
    ibm-slapdMasterReferral: ldap://peer1hostname:peer1port/  
    

    Note:

    This ensures that all updates from the clients are referred to peer1.

15. Copy <masterfile.ldif> to the machines where forwarder1 and forwarder2 are located.
16. At each of these machines, issue the following command:

    ldif2db -r no -i <masterfile.ldif>
    

17. Ensure that replica1, replica2, replica3, and replica4 are stopped.
18. You must configure replica1, replica2, replica3, and replica4 to be replica servers. Use an editor to add the following stanza to the ibmslapd.conf files on each of the replicas:

    dn: cn=MasterServer, cn=configuration
    cn: Master Server
    ibm-slapdMasterDN: cn=master
    ibm-slapdMasterPW: master
    ibm-slapdMasterReferral: ldap://peer1hostname:peer1port/     
    

19. Save the ibmslapd.conf files.
20. Copy <masterfile.ldif> to the machines where replica1, replica2, replica3, and replica4 are located.
21. At each of these machines, issue the following command:

    ldif2db -r no -i <masterfile.ldif>
    

22. Start peer1, peer2, forwarder1, forwarder2, replica1, replica2, replica3, and replica4.

Specifying a supplier DN and password for a subtree

You can specify a supplier DN and PW for a particular subtree. To do this the following information is needed on the replica and master.

To create a replica for a subtree, you need to create a replica agreement between the master and the replica, see Replication agreements. This agreement needs to be loaded on both the master and the replica. The relationship between the two servers is that the master is a supplier to the replica and the replica is a consumer of the master.

1. At the machine where the master is located, create a file to contain the agreement information, for example, mysupplierinfofile, where mysupplierinfofile contains:

   #Replication data on the master:
    
   dn: o=IBM,c=US
   objectclass: organization
    
   dn: ou=Test,o=IBM,c=US
   objectclass: organizationalunit
   objectclass: ibm-replicationContext
   aclentry: access-id:CN=this:object:a:normal:rwsc:sensitive:rwsc:critical:rwsc
   entryowner: access-id:CN=this
    
   dn: ibm-replicaGroup=default, ou=Test,o=IBM,c=US
   objectclass: top
   objectclass: ibm-replicaGroup
   ibm-replicaGroup: default
    
   dn: cn=replica1 BindCredentials, cn=localhost
   objectclass: ibm-replicationCredentialsSimple
   cn: replica1 BindCredentials
   replicaBindDN: cn=s1
   replicaCredentials: s1
   description: Bindmethod of master to replica1
    
   dn: ibm-replicaServerId=<master-uuid>,ibm-replicaGroup=default,
       ou=Test,o=IBM,c=US
   #master uuid is whatever the server ID is set to in your ibmslapd.conf 
   #on the master.
   objectclass: top
   objectclass: ibm-replicaSubentry
   ibm-replicaServerId: <master-uuid>
   ibm-replicationServerIsMaster: true
   cn: master
   description: master server
    
   dn: cn=replica1,ibm-replicaServerId=<master-uuid>,ibm-replicaGroup=default,
      ou=Test,o=IBM,c=US
   objectclass: top
   objectclass: ibm-replicationAgreement
   cn: replica1
   ibm-replicaConsumerId: <replica1-uuid>
   #<replica1-uuid> is whatever the server ID is set to in your 
   #replica ibmslapd.conf file.
   ibm-replicaUrl: ldap://<replica1hostname:replica1port>
   ibm-replicaCredentialsDN: cn=replica1 BindCredentials, cn=localhost
   description: replica server number one
   

2. Stop the master, if it is not already stopped.
3. Issue the command:

   ldif2db -r no -i <mysupplierinfofile>
   

4. Issue the command:

   db2ldif -o <masterfile.ldif>
   

   See db2ldif utility for more information.

5. Copy <masterfile.ldif> to the machine where replica1 is located.
6. Stop the replica if it is running.
7. You must configure replica1 to be a replica server. Use an editor to add the following stanza to the ibmslapd.conf file on replica1:

   dn: cn=MasterServer, cn=configuration
   cn: Master Server
   ibm-slapdMasterDN: cn=master
   ibm-slapdMasterPW: <masterserverpassword>
   ibm-slapdMasterReferral: ldap://<masterhostname:masterport>
   objectclass: ibm-slapdReplication
    
   dn: cn=Supplier s1, cn=configuration
   cn: Supplier s1
   ibm-slapdMasterDN: cn=s1
   ibm-slapdMasterPW: s1
   ibm-slapdReplicaSubtree: ou=Test, o=IBM, c=US
   objectclass: ibm-slapdSupplier
    
    
    
   

8. Save the ibmslapd.conf file.
9. Issue the following command:

   ldif2db -r no -i <masterfile.ldif>
   

10. Start master and replica1.

Viewing replication configuration information

A great deal of information related to replication activity is available using searches. To see the replication topology information related to a particular replicated subtree, you can do a one-level search with the base set to the DN of the subtree and the filter set as (objectclass=ibm-replicaGroup) to find the subentry that is the base of the topology information. If this replication context was created through the web admin interface, the name of the entry will be ibm-replicaGroup=default.

ldapsearch -D <adminDN> -w <adminPW> -b <suffixentryDN> (objectclass=*)
 

The objects returned will include the replica group itself, plus the following:

• An object with objectclass=ibm-replicaSubentry for each server that replicates data within this context. Replica subentries contain a server id attribute and an indication of the role the server plays (ibm-replicationServerIsMaster).
• For each replica subentry, there is a replication agreement object for each consumer server that receives replication updates from the server described by the replica subentry. Each replication agreement contains the following information:
  • ibm-replicaConsumerId: The server id of the consumer server.
  • ibm-replicaURL: The LDAP URL of the consumer server.
  • ibm-replicaCredentialsDN: The DN of the entry containing the credentials used to bind to the consumer.

  Agreements may also contain the following:

  • ibm-replicaScheduleDN: The DN of a schedule entry that determines when replication updates are sent to this consumer. If no schedule is specified, replication defaults to "immediate" mode.
  • ibm-replicationOnHold: A boolean indicating that replication to this consumer is suspended (or not).
  • ibm-replicationExcludedCapability: The values of this attribute list OIDs of features that the consumer does not support. Operations related to these capabilities are then excluded from the updates sent to this consumer.

Monitoring Replication Status

In addition, there are many operational attributes that provide replication status information when explicitly requested on a search. One of these attributes is associated with the entry that is the base of the replicated subtree, that is, the entry that the ibm-replicationContext objectclass was added to. If you do a base search of that entry, and request that the ibm-replicationIsQuiesced attribute is returned. This attribute is a boolean that indicates if the subtree has been quiesced. If the subtree is quiesced, no client updates are allowed (only updates from replication suppliers are accepted). There is an extended operation that can be used to quiesce a subtree, see ldapexop.

The remainder of the status-related operational attributes are all associated with a replication agreement object. These attributes are only returned when explicitly requested on the search. The attributes available are:

• ibm-replicationLastActivationTime: The time that the last replication session started between this supplier and consumer.
• ibm-replicationLastFinishTime: The time that the last replication session finished between this supplier and consumer.
• ibm-replicationLastChangeId: The change ID of the last update sent to this consumer.
• ibm-replicationLastGlobalChangeId: The change ID of the last update to a global entry sent to this consumer. Global entries are things like cn=schema or cn=pwdpolicy that apply to the entire contents of a DIT.
• ibm-replicationState: The current state of replication with this consumer. Possible values are:

  Active

  Actively sending updates to consumer (possibly retrying due to errors).

  Ready

  In immediate replication mode, ready to send updates as they occur.

  Waiting

  Waiting for next scheduled replication time.

  Binding

  In the process of binding to the consumer.

  Connecting

  In the process of connecting to the consumer.

  OnHold

  This replication agreement has been suspended or "held".

• ibm-replicationLastResult The results of the last attempted update to this consumer, in the form:

  <time stamp> <change id> <result code> <operation> <entry DN>
  

• ibm-replicationLastResultAdditional: Any additional error information returned from the consumer for the last update.
• ibm-replicationPendingChangeCount: The number of updates queued to be replicated to this consumer.
• ibm-replicationPendingChanges: Each value of this attribute gives information about one of the pending changes in the form:

  <change id> <operation> <entry DN>
  

  Requesting this attribute might return many values. Check the change count before requesting this attribute.

• ibm-replicationChangeLDIF: Gives the full details of the last failing update in LDIF.

Logging Utilities

The IBM Directory Server Version 5.1 provides several logging utilities that can be viewed either through the Web Administration Tool or the system command line.

Notes:

1. In the Web Administration Tool the Logfiles field in the task title bar accesses the Web Administration console log files. The IBM Directory Server log files are accessible by using the procedures specified in the following sections.

2. On Windows-based systems, if a path begins with the drive letter and a colon, it is assumed to be the full path. A path without the drive letter, starts in the installation tree. As examples: c:\tmp\mylog is a full path, while \tmp\mylog is interpreted as c:\program files\ibm\ldap\tmp\mylog.

Modifying error logging

The error log, ibmslapd.log, is enabled by default, to modify the error log settings:

1. Expand Server administration in the navigation area, click Logs, click Modify error log settings.
2. Enter the path and file name for the error log. Ensure that the path is valid. If the file does not exist, it is created. The error log can also be directed to something other than a file, for example, a line printer.

   Note:

   If you specify a file that is not an acceptable file name (for example, invalid syntax or if the server does not have the rights to create and/or modify the file), the attempt fails with the following error: LDAP Server is unwilling to perform the operation.

3. Select either Low, Medium, or High for the level of error logging.
   • Low logs the least amount of error information, for example,

     Mar 29 11:03:23 2002  IBM Directory, Version 5.1
     slapd started.  
     

   • Medium logs a medium amount of error information, for example,

     Mar 29 11:07:51 2002  Configuration read securePort 636.
     Mar 29 11:07:51 2002  Plugin of type PREOPERATION is successfully 
                           loaded from libDSP.dll.
     Mar 29 11:07:51 2002  Plugin of type DATABASE is successfully loaded from 
                           C:\Program Files\IBM\LDAP/bin/libback-rdbm.dll.
     Mar 29 11:08:11 2002  Non-SSL port initialized to 389.
     Mar 29 11:08:12 2002  IBM Directory, Version 5.1
     slapd started.
     

   • High logs the most amount of error information, for example

     Mar 29 11:04:05 2002  Configuration read securePort 636.
     Mar 29 11:04:05 2002  Configuration read cipher specifications 
                           mask to be 12288.
     Mar 29 11:04:05 2002  Plugin of type PREOPERATION is successfully 
                           loaded from libDSP.dll.
     Mar 29 11:04:05 2002  Plugin of type DATABASE is successfully loaded from 
                           C:\Program Files\IBM\LDAP/bin/libback-rdbm.dll
     Mar 29 11:04:24 2002  Configuration file successfully read.
     Mar 29 11:04:24 2002  Non-SSL port initialized to 389.
     Mar 29 11:04:25 2002  IBM Directory, Version 5.1
     slapd started. 
     

4. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.
5. Click OK to return to the IBM Directory Server Web Administration Welcome panel.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN <-w >AdminPW> -i <filename>

where <filename> contains:

dn: cn=Configuration
changetype: modify
replace: ibm-slapdErrorLog
ibm-slapdErrorLog: <newpathname>
-
replace: ibm-slapdSysLogLevel
ibm-slapdSysLogLevel: {l | m | h}

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope entire

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Viewing the error log

Use the following procedures to view the error log.

Using Web Administration:

1. Expand Logs in the navigation area, then click View error log.
2. You can:
   • The panel displays the first page of the error log and the navigation arrows at the bottom of the panel allow you to go to the Next page or to the Previous page.
   • From the drop-down menu, you can select a specific page, for example Page 6 of 16, and click Go to display that page of the error log.
   • Click Clear log to delete all entries in the error log.

Using the command line:

To view the error log issue the following command:

more /var/ldap/ibmslapd.log

where var/ldap/ibmslapd.log is your error log.

Note:

var/ldap/ibmslapd.log is the default error log for UNIX systems and installpath\var\ibmslapd.log is the default error log for Windows systems.

To view and clear the error log dynamically:

ldapexop -D cn=root -w root -op readlog -log  slapd  -lines all
ldapexop -D cn=root -w root -op clearlog -log  slapd
 

Note:

Only the administrator is allowed to access the log files.

Audit Logging

Audit logging is used to improve the security of the directory server. A default audit plug-in is provided with the server. Depending on the audit configuration parameters, this plug-in might log an audit entry in the default or specified audit log for each LDAP operation the server processed. The system administrator can use the activities stored in the audit log to check for suspicious patterns of activity in an attempt to detect security violations. If security is violated, the audit log can be used to determine how and when the problem occurred and perhaps the amount of damage done. This information is very useful, both for recovery from the violation and, possibly, in the development of better security measures to prevent future problems. You can also write your own audit plug-ins to either replace, or add more processing to, the default audit plug-in.

By default the audit log is disabled.

Enabling the audit log and modifying audit log settings

To enable audit logging:

1. Expand Logs in the navigation area, click Modify audit log settings.
2. Select Enable audit logging to use the audit log utility.
3. Select to either log Only failed attempts of the selected operations or to log All attempts of the selected operations.
4. Enter the Path and file name for the audit log. The audit log can also be directed to something other than a file, for example, a line printer.
5. Select the operations you wish to log. Consult the field help for additional information about the various operations you can log.
   • Bind - records connections to the server
   • Unbind - records disconnections from the server
   • Search - records LDAP search operations performed by any client
   • Add - records additions to LDAP
   • Modify - records modifications to LDAP
   • Delete - records deletions from LDAP
   • Modify RDN - records modifications made to RDN's
   • Event notification - records event notifications
6. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.
7. If you click OK, a message is displayed to remind you that you need to restart the server.

   Note:

   If you have enabled audit logging, you must restart the server for the changes to take effect. If you were modifying only the settings, the server does not need to be restarted.

   Click OK to return to the IBM Directory Server Web Administration Welcome panel.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN> -w <AdminPW> -i <filename>

where <filename> contains:

dn: cn=audit, cn=localhost
changetype: modify
replace: ibm-audit
ibm-audit: true
 
-
replace: ibm-auditadd
ibm-auditadd: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditbind
ibm-auditbind: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditdelete
ibm-auditdelete: TRUE|FALSE
-
replace: ibm-auditextopevent
ibm-auditextopevent: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditfailedoponly
ibm-auditfailedoponly: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditlog
ibm-auditlog: <newpathname>
-
replace: ibm-auditmodify
ibm-auditmodify: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditmodifydn
ibm-auditmodifydn: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditsearch
ibm-auditsearch: TRUE|FALSE
#select TRUE to enable, FALSE to disable
-
replace: ibm-auditunbind
ibm-auditunbind: TRUE|FALSE
#select TRUE to enable, FALSE to disable
 

Note:

If you are using audit logging in Configuration only mode, the DN specified is dn: cn=audit, cn=configuration. Any changes made to this DN are overwritten with the dn: cn=audit, cn=localhost values when the server is started in normal mode.

Disabling the audit log

To disable audit logging:

1. Expand Logs in the navigation area, click Modify audit log settings.
2. Deselect Enable audit logging.
3. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN> -w <AdminPW> -i <filename>

where <filename> contains:

dn: cn=audit, cn=localhost
changetype: modify
replace: ibm-audit
ibm-audit: flase
 

Note:

If you are using audit logging in Configuration only mode, the DN specified is dn: cn=audit, cn=configuration. Any changes made to this DN are overwritten with the dn: cn=audit, cn=localhost values when the server is started in normal mode.

Viewing the audit log

The audit log displays log entries chronologically. Each non-message entry contains a general information header followed by operation-specific data. For example,

2000-03-23-16:01:01.345-06:00--V3 Bind--bindDN:Y249bWFuYWdlcg0K
   --client:9.1.2.3:12345--
ConnectionID:12--received:2000-03-23-16:01:01.330-06:00
   --success name: Y249bWFuYWdlcg0K 
authenticationChoice: simple
 

The header is in the following format:

Timestamp 1 "--"

The local time the entry is logged, that is, the time the request was processed. The timestamp is in the format YYYY-MM-DD-HH:MM:SS.mmm=(or-)HH:MM. The =(or=)HH:MM is UTC offset. mmm is milliseconds.

Version number+[SSL]+[unauthenticated or anonymous] Operation "--"

Shows the LDAP request that was received and processed. Version number is either V2 or V3. SSL displays only when SSL was used for the connection. unauthenticated or anonymous displays to indicate whether the request was from an unauthenticated or anonymous client. Neither unauthenticated or anonymous display if the request is from an authenticated client.

bindDN: server encoded DN string "--"

Shows the Bind DN. The encoding done by the server is to hide the DN from trivial viewing. The server provides a decoding function through an LDAP search of special audit related attributes. For V3 unauthenticated or anonymous requests, this field is not shown.

client:Client IP address:Port number "--"

Shows the client IP address and port number.

ConnectionID: xxxx "--"

Is used to group all the entries received in the same connection, meaning between the bind and unbind, together.

received: Timestamp 2 "--"

Is the local time when the request was received, or to be more specific, the beginning time when the request was processed. Its format is the same as Timestamp 1.

Result or Status string

Shows the result or status of the LDAP operation. For the result string, the textual form of the LDAP resultCode is logged, for example, success or operationsError, instead of 0 or 1.

Operation-specific data follows the header and displays operation-specific data, for example,

• Bind operations

  name: Y249bWFuYWdlcg0K 
  authenticationChoice: simple                  
  

• Add operations

  entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us 
  attributes: objectclass, cn, sn, telphonenumber                 
  

• Delete operations

  entry:  cn=Jim Brown, ou=sales,o=ibm_us,c=us                
  

• Modify operations

  object: cn=Jim Brown, ou=sales,o=ibm_us,c=us 
  add: mail 
  delete: telephonenumber                  
  

Use the following procedures to view the audit log:

Using Web Administration:

To view the audit log :

1. Expand Logs in the navigation area, click View audit log.
2. You can:
   • The panel displays the first page of the audit log and the navigation arrows at the bottom of the panel allow you to go to the Next page or to the Previous page.
   • From the drop-down menu, you can select a specific page, for example Page 6 of 16, and click Go to display that page of the audit log.
   • Click Clear log to delete all entries in the audit log.

Using the command line:

To view the error log issue the following command:

more /var/ldap/audit.log

where /var/ldap/audit.log is your error log.

Note:

/var/ldap/audit.log is the default audit log for UNIX systems and installpath\var\audit.log is the default audit log for Windows systems.

To view and clear the audit log dynamically:

ldapexop -D cn=root -w root -op readlog -log audit -lines all
ldapexop -D cn=root -w root -op clearlog -log audit
 

Note:

Only the administrator is allowed to access the log files.

DB2 error logging

Modifying DB2 error log settings

1. Expand Logs in the navigation area, click Modify DB2 log settings.
2. Enter the path and file name for the error log. Typically this is the db2cli.log file located in the /var/ldap directory. Ensure that the path is valid. If the file does not exist, it is created.

   Note:

   var/ldap/db2cli.log is the default DB2 error log for UNIX systems and installpath\var\db2cli.log is the default DB2 error log for Windows systems.

3. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.
4. Click OK to return to the IBM Directory Server Web Administration Welcome panel.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN> -w <AdminPW> -i <filename>

where <filename> contains:

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
replace: ibm-slapdCLIErrors
ibm-slapdCLIErrors: <newpathname>
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope single 
      "cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" 
      ibm-slapdCLIErrors

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Viewing the DB2 error log

Use the following procedures to view the DB2 error log.

Using Web Administration:

1. Expand Logs in the navigation area, then click View DB2 log.
2. You can:
   • The panel displays the first page of the DB2 error log and the navigation arrows at the bottom of the panel allow you to go to the Next page or to the Previous page.
   • From the drop-down menu, you can select a specific page, for example Page 6 of 16, and click Go to display that page of the DB2 error log.
   • Click Clear log to delete all entries in the DB2 error log.

Using the command line:

To view the DB2 error log issue the following command:

more /var/ldap/db2cli.log

where var/ldap/db2cli.log is your DB2 error log.

Note:

var/ldap/db2cli.log is the default DB2 error log for UNIX systems and installpath\var\db2cli.log is the default DB2 error log for Windows systems.

To view and clear the DB2 error log dynamically:

ldapexop -D cn=root -w root -op readlog -log  cli  -lines all
ldapexop -D cn=root -w root -op clearlog -log  cli 
 

Note:

Only the administrator is allowed to access the log files.

bulkload error logging

Modifying bulkload error log settings

1. Expand Logs in the navigation area, click Modify bulkload log settings.
2. Enter the path and file name for the error log. Typically this is the bulkload.log file located in the var/ldap directory. Ensure that the file exists on the ldap server and that the path is valid.

   Note:

   var/ldap/bulkload.log is the default bulkload error log for UNIX systems and installpath\var\bulkload.log is the default bulkload error log for Windows systems.

3. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.
4. If you click OK, a message is displayed to remind you that you need to restart the server. Click OK to return to the IBM Directory Server Web Administration Welcome panel.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN> -w <AdminPW> -i <filename>

where <filename> contains:

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
replace: ibm-slapdBulkloadErrors
ibm-slapdBulkloadErrors: <newpathname>
 

To update the settings dynamically issue the following ldapexop command:

ldapexop -D cn=root -w root -op readconfig -scope single 
      "cn=Directory,cn=RDBM Backends,cn=IBM Directory,cn=Schemas,cn=Configuration" 
      ibm-slapdBulkloadErrors

The ldapexop command only updates those attributes that are dynamic. For other changes to take effect you must stop and restart the server. See Dynamically-changed attributes for a list of the attributes that can be updated dynamically.

Viewing the bulkload error log

Use the following procedures to view the bulkload error log.

Using Web Administration:

1. Expand Logs in the navigation area, then click View bulkload log.
2. You can:
   • The panel displays the first page of the bulkload error log and the navigation arrows at the bottom of the panel allow you to go to the Next page or to the Previous page.
   • From the drop-down menu, you can select a specific page, for example Page 6 of 16, and click Go to display that page of the bulkload error log.
   • Click Clear log to delete all entries in the bulkload error log.

Using the command line:

To view the bulkload error log issue the following command:

more /var/ldap/bulkload.log

where var/ldap/bulkload.log is your bulkload error log.

Note:

var/ldap/bulkload.log is the default error log for UNIX systems and installpath\var\bulkload.log is the default bulkload error log for Windows systems.

To view and clear the bulkload error log dynamically:

ldapexop -D cn=root -w root -op readlog -log bulkload -lines all
ldapexop -D cn=root -w root -op clearlog -log bulkload

Note:

Only the administrator is allowed to access the log files.

Administration daemon error logging

Modifying administration daemon error log settings

1. Expand Logs in the navigation area, click Modify admin daemon log settings.
2. Enter the path and file name for the Web Administration error log. Typically this is the ibmdiradm.log file located in the var/ldap/ directory. Ensure that the file exists on the ldap server and that the path is valid.

   Note:

   var/ldap/ibmdiradm.log is the default Web Administration error log for UNIX systems and installpath\var\ibmdiradm.log is the default Web Administration error log for Windows systems.

3. Click OK to apply your changes or click Cancel to return to the IBM Directory Server Web Administration Welcome panel without making any changes.
4. If you click OK, a message is displayed to remind you that you need to restart the server. Click OK to return to the IBM Directory Server Web Administration Welcome panel.
5. You must restart the administration daemon for the changes to take effect.

Using the command line:

Issue the command:

ldapmodify -D <AdminDN <-w >AdminPW> -i <filename>

where <filename> contains:

dn: cn=Admin, cn=Configuration
changetype: modify
replace: ibm-slapdErrorLog
ibm-slapdErrorLog: <newpathname>
 

Viewing the administration daemon error log

Use the following procedures to view the administration daemon error log.

Using Web Administration:

1. Expand Logs in the navigation area, then click View admin deamon log.
2. You can:
   • The panel displays the first page of the Web Administration error log and the navigation arrows at the bottom of the panel allow you to go to the Next page or to the Previous page.
   • From the drop-down menu, you can select a specific page, for example Page 6 of 16, and click Go to display that page of the Web Administration error log.
   • Click Clear log to delete all entries in the administration daemon error log.

Using the command line:

To view the administration daemon error log issue the following command:

more /var/ldap/ibmdiradm.log

where var/ldap/ibmdiradm.log is your Web Administration error log.

Note:

var/ldap/ibmdiradm.log is the default Web Administration error log for UNIX systems and installpath\var\ibmdiradm.log is the default Web Administration error log for Windows systems.

To view and clear the Web Administration error log dynamically:

ldapexop -D cn=root -w root -op readlog -log  ibmdiradm  -lines all
ldapexop -D cn=root -w root -op clearlog -log  ibmdiradm

Note:

Only the administrator is allowed to access the log files.

Directory Management

Working with directory entries

Expand the Directory management category in the navigation area of the Web Administration Tool. All the directory entry tasks that you want to perform can be accessed by selecting Manage entries. Two short cuts have been added to the navigation area for the specific tasks of adding an entry and finding (searching for) entries

You can perform the following operations with directory entries:

• Browse the directory tree
• Add or create an entry
• Add or delete an auxiliary object class to an entry
• Edit the attributes of an entry
• Copy an entry
• Edit ACLs
• Search for entries

Browsing the tree

If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the entry that you want to work on. You can choose the operation you want to perform from the right-side tool bar.

Adding an entry

If you have not done so already, expand the Directory management category in the navigation area.

1. Click Add an entry.
2. Select one Structural object class from the drop-down list .
3. Click Next.
4. Select any Auxiliary object classes you wish to use from the Available box and click Add. Repeat this process for each auxiliary object class you want to add. You can also delete an auxiliary object class from the Selected box by selecting it and clicking Remove.
5. Click Next.
6. In the Relative DN field, enter the relative distinguished name (RDN) of the entry that you are adding, for example, cn=John Doe.
7. In the Parent DN field, enter the distinguished name of the tree entry you selected, for example, ou=Austin, o=IBM. You can also click Browse to select the Parent DN from the list. You can also expand the selection to view other choices lower in the subtree. Specify the your choice and click Select to specify the Parent DN that you want. The Parent DN defaults to the entry selected in the tree.

   Note:

   If you started this task from the Manage entries panel, this field is prefilled for you. You selected the Parent DN before clicking Add to start the add entry process.

8. At the Required attributes tab enter the values for the required attributes. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
9. Click Optional attributes.
10. At the Optional attributes tab enter the values as appropriate for the optional attributes. See Binary attributes for information on adding binary values. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
11. Click OK to create the entry.
12. Click the ACL button to modify the access control list for this entry. See Working with Access Control Lists for information on ACLs.
13. After completing at least the required fields, click Add to add the new entry or click Cancel to return to Browse tree without making changes to the directory.

Deleting an entry

If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the subtree, the suffix, or the entry that you want to work on. Click Delete from the right-side tool bar.

• You are requested to confirm the deletion. Click OK.
• The entry is deleted from the entry and you are returned to the list of entries.

Editing an entry

If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the entry that you want to work on. Click Edit attributes from the right-side tool bar.

1. At the Required attributes tab enter the values for the required attributes. See Binary attributes for information on adding binary values. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
2. Click Optional attributes.
3. At the Optional attributes tab enter the values as appropriate for the optional attributes. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
4. Click Memberships.
5. If you have created any groups, at the Memberships tab:
   • Select a group from Available groups and click Add to make the entry a member of the selected Static group membership.
   • Select a group from Static group memberships and click Remove to remove the entry from the selected group.
6. If the entry is a group entry, a Members tab is available. The Members tab displays the members of the selected group. You can add and remove members from the group.
   • To add a member to the group:
     1. Either click Multiple values by the Members tab or at the Members tab, click Members.
     2. In the Member field, enter the DN of the entry you want to add.
     3. Click Add.
     4. Click OK.
   • To remove a member from the group:
     1. Either click Multiple values by the Members tab or click the Members tab and click Members.
     2. Select the entry you want to remove.
     3. Click Remove.
     4. Click OK.
   • To refresh the members list, click the Update.
7. Click OK to modify the entry.

Binary attributes

If an attribute requires binary data, a Binary data button is displayed next to the attribute field. If the attribute has no data the field is blank. Because binary attributes cannot be displayed, if an attribute contains binary data, the field displays Binary Data - 1. If the attribute contains multiple values, the field displays as a drop-down list.

Click the Binary data button to work with binary attributes.

You can import, export or delete binary data.

To add binary data to the attribute:

1. Click the Binary data button.
2. Click Import.
3. You can either enter the path name for the file you want or click Browse to locate and select the binary file.
4. Click Submit file. A File uploaded message is displayed.
5. Click Close. Binary Data - 1 is now displayed under Binary data entries.
6. Repeat the import process for as many binary files as you want to add. The subsequent entries are listed as Binary Data - 2, Binary Data -3, and so on.
7. When you are finished adding binary data, click OK.

To export binary data:

1. Click the Binary data button.
2. Click Export.
3. Click on the link Binary data to download.
4. Follow the directions of your wizard to either display the binary file or to save it to a new location.
5. Click Close.
6. Repeat the import process for as many binary files as you want to export.
7. When you are finished exporting data, click OK.

To delete binary data:

1. Click the Binary data button.
2. Check the binary data file you want to delete. Multiple files can be selected.
3. Click Delete.
4. When you are prompted to confirm the deletion, click OK. The binary data marked for deletion are removed from the list.
5. When you are finished deleting data, click OK.

Note:

Binary attributes are not searchable.

Copying an entry

This function is useful if you are creating similar entries. The copy inherits all the attributes of the original. You need to make some modifications to name the new entry.

If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the entry, such as John Doe, that you want to work on. Click Copy from the right-side tool bar.

• Change the RDN entry in the DN field. For example change cn=John Doe to cn=Jim Smith.
• On the required attributes tab, change the cn entry to the new RDN. In this example Jim Smith.
• Change the other required attributes as appropriate. In this example change the sn attribute from Doe to Smith.
• When you have finished making the necessary changes click OK to create the new entry.
• The new entry Jim Smith is added to the bottom of the entry list.

Note:

This procedure copies only the attributes of the entry. The group memberships of the original entry are not copied to the new entry. Use the Edit attributes function to add memberships.

Editing access control lists

To view ACL properties using the Web Administration Tool utility and to work with ACLs, see Working with Access Control Lists.

See Access Control Lists for additional information.

Adding an auxiliary object class

Use the Add auxiliary class button on the toolbar to add an auxiliary object class to an existing entry in the directory tree. An auxiliary object class provides additional attributes to the entry to which it is added.

If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the entry, such as John Doe, that you want to work on. Click Add auxiliary class from the right-side tool bar.

1. Select any Auxiliary object classes you wish to use from the Available box and click Add. Repeat this process for each auxiliary object class you want to add. You can also delete an auxiliary object class from the Selected box by selecting it and clicking Remove.
2. At the Required attributes tab enter the values for the required attributes. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
3. Click Optional attributes.
4. At the Optional attributes tab enter the values as appropriate for the optional attributes. If you want to add more than one value for a particular attribute, click Multiple values and then add the values one at a time.
5. Click Memberships.
6. If you have created any groups, at the Memberships tab:
   • Select a group from Available groups and click Add to make the entry a member of the selected Static group membership.
   • Select a group from Static group memberships and click Remove to remove the entry from the selected group.
7. Click OK to modify the entry.

Deleting an auxiliary class

Although you can delete an auxiliary class during the add auxiliary class procedure, it is easier to use the delete auxiliary class function if you are going to delete a single auxiliary class from an entry. However, it might be more convenient to use the add auxiliary class procedure if you are going to delete multiple auxiliary classes from and entry.

1. If you have not done so already, expand the Directory management category in the navigation area, then click Manage entries. You can expand the various subtrees and select the entry, such as John Doe, that you want to work on. Click Delete auxiliary class from the right-side tool bar.
2. From the list of auxiliary classes select the one you want to delete and press OK.
3. You are asked to confirm the deletion, click OK.
4. The auxiliary class is deleted from the entry and you are returned to the list of entries.

Repeat these steps for each auxiliary class that you want to delete.

Changing group membership

If you have not done so already, expand the Directory management category in the navigation area.

1. Click Manage entries.
2. Select a user from the directory tree and click the Edit attributes icon on the toolbar. tree.
3. Click the Memberships tab.
4. To modify the memberships for the user. The Change memberships panel displays the Available groups to which the user can be added, as well as the entry's Static Group Memberships.
   • Select a group from Available groups and click Add to make the entry a member of the selected group.
   • Select a group from Static Group Memberships and click Remove to remove the entry from the selected group.
5. Click OK to save your changes or click Cancel to return to the previous panel without saving your changes.

Searching the directory entries

There are three options for searching the directory tree:

• A Simple search using a predefined set of search criteria
• An Advanced search using a user-defined set of search criteria
• A Manual search

The search options are accessible by expanding the Directory management category in the navigation area, click Find entries. Select one of the following tabs:

Note:

Binary entries, for example passwords, are not searchable.

Search filters

Select on of the following types of searches:

Simple search

A simple search uses a default search criteria:

• Base DN is All suffixes
• Search scope is Subtree
• Search size is Unlimited
• Time limit is Unlimited
• Alias dereferencing is never
• Chase referrals is deselected (off)

To perform a simple search:

1. On the Search filter tab, click Simple search.
2. Select an object classes from the drop-down list.
3. Select a specific attribute for the selected entry type. If you select to search on a specific attribute, select an attribute from the drop-down list and enter the attribute value in the Is equal to box. If you do not specify an attribute, the search returns all the directory entries of the selected entry type.

Advanced search

An advanced search enables you to specify search constraints and enable search filters. Use the Simple search to use default search criteria.

• To perform an advanced search:
  1. On the Search filter tab, click Advanced search.
  2. Select an Attribute from the drop-down list.
  3. 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.
  4. Enter the Value for comparison.
  5. Use the search operator buttons for complex queries.
     • If you already added at least one search filter, specify the additional criteria and click AND. The AND command returns entries that match both sets of search criteria.
     • If you already added at least one search filter, specify the additional criteria and click OR. The OR command returns entries that match either set of search criteria.
  6. • Click Add to add the search filter criteria to the advanced search
     • Click Delete to remove the search filter criteria from the advanced search
     • Click Reset to clear all search filters.

Manual search

Use this method to create a search filter. For example to search on surnames enter sn=* in the field. If you are searching on multiple attributes, you must use search filter syntax. For example to search for the surnames of a particular department you enter:

(&(sn=*)(dept=<departmentname>))

Options

At the Options tab:

• Search base DN - Select suffix from the drop-down list to search only within that suffix.

  Note:

  If you started this task from the Manage entries panel, this field is prefilled for you. You selected the Parent DN before clicking Add to start the add entry process.

  You can also select All suffixes to search the entire tree.
• 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 select Unlimited.
• Search time limit - Enter the maximum number of seconds for the search or select 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 a referral is returned in the search. When a referral directs the search to another server, the connection to the server uses the current credentials. If you are logged in as Anonymous you might need to log in to the server using an authenticated DN. See Logging on to the Web Administration Tool for information about logging in. See Referrals for more information about referrals.

See Setting Searches for additional information about searches.

Access Control Lists

Access Control Lists (ACL) provide a means to protect information stored in a LDAP directory. Administrators use ACLs to restrict access to different portions of the directory, or specific directory entries. LDAP directory entries are related to each other by a hierarchical tree structure. Each directory entry (or object) contains the distinguished name of the object as well as a set of attributes and their corresponding values.

The object attributes associated with access control, such as owner, ownerSource, ownerPropagate, aclEntry, aclSource and aclPropagate are unusual in that they are logically associated with each object, but can have values that depend upon 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 Control Information (ACI) and the entryOwner Information. The ACI specifically defines a subject's permission to perform a given operation against certain LDAP objects. The entryOwner information controls which subjects can define the ACIs. The entryOwnership also acquires full access rights to the target object.

Using ACL, administrators can restrict access to different portions of the directory, specific directory entries and, based on the attribute name or attribute access class, the attributes contained in the entries. Each entry within the LDAP directory has a set of associated ACI. In conformance with the LDAP model, the ACI and entryOwner information is represented as attribute-value pairs. Furthermore, the LDIF syntax is used to administer these values. The attributes are:

• aclEntry
• aclPropagate
• entryOwner
• ownerPropagate

Filtered ACLs

In the current access control model, ACLs apply explicitly to the directory entry that contains them, but may be propagated to none, or all of its descendant entries. Filter-based ACLs differ in that they employ a filter-based comparison, using a specified object filter, to match target objects with the effective access that applies to them.

Although they perform the same function, the behavior of the two types of ACLs is significantly different. Filter-based ACLs do not propagate in the same way that non-filter-based ACLs currently do. By nature, they inherently propagate to any comparison matched objects in the associated subtree. For this reason, the aclPropagate attribute, which is used to stop propagation of non-filter ACLs, does not apply to the new filter-based ACLs.

The default behavior of filter-based ACLs to accumulate from the lowest containing entry, upward along the ancestor entry chain, to the highest containing entry in the DIT. The effective access is calculated as the union of the access rights granted, or denied, by the constituent ancestor entries. There is an exception to this behavior. For compatibility with the subtree replication feature, and to allow greater administrative control, a ceiling attribute is used as a means to stop accumulation at the entry in which it is contained.

A new set of access control attributes are used specifically for filter-based ACL support, rather than merging filter-based characteristics into the existing non-filter based ACLs. The attributes are:

• ibm-filterAclEntry
• ibm-filterAclInherit

The ibm-filterAclEntry attribute has the same format as aclEntry, with the addition of an object filter component. The associated ceiling attribute is ibm-filterAclInherit. By default it is set to true. When set to false, it terminates the accumulation.

The access control attribute syntax

Each of these attributes can be managed using LDIF notation. The syntax for the new filter-based ACL attributes are modified versions of the current non-filter-based ACL attributes.The following defines the syntax for the ACI and entryOwner attributes using baccus naur form (BNF).

 <aclEntry> ::=  <subject> [ ":"  <rights> ] 
 
 <aclPropagate> ::=  "true" | "false" 

 <ibm-filterAclEntry> ::=  <subject>  ":" <object filter>  [ ":"  <rights> ] 
 
 <ibm-filterAclInherit> ::=  "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" 
 

 <object filter> ::= string search filter as defined in RFC 2254, section 4
  	           	         (extensible matching is not supported).

 <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 or alpha-numeric string with leading 
                         alphabet, "-" and ";" allowed) 
 
 <attributePermissions> ::=  <attributePermission> 
                                   [<attributePermissions>] 
 
 <attributePermission> ::=  "r" | "w" | "s" | "c" |  "" 
 
 <attributeClassAccess> ::= <class> ":" [<action> ":"] 
                                     <attributePermissions> 
 
 <class> ::= "normal" | "sensitive" | "critical" 
  
 

AclEntry and ibm-filterAclEntry

Subject

A subject (the entity requesting access to operate on an object) consists of the combination of a DN (Distinguished Name) type and a DN. The valid DN types are: access Id, Group and Role.

The DN identifies a particular access-id, role or group. For example, a subject might be access-id: cn=personA, o=IBM or group: cn=deptXYZ, o=IBM.

Because the field delimiter is the colon ( : ), a DN containing colons must be surrounded by double-quotation marks ( "" ). If a DN already contains characters with double-quotation marks, these characters must be escaped with a backslash (\).

All directory groups can be used in access control.

Note:

Any group of AccessGroup, GroupOfNames, GroupofUniqueNames, or groupOfURLs structural objectclasses or the ibm-dynamicGroup, ibm-staticGroup auxiliary objectclasses can be used for access control.

Another DN type used within the access control model is role. While roles and groups are similar in implementation, conceptually they are different. When a user is assigned to a role, there is an implicit expectation that the necessary authority has already been set up to perform the job associated with that role. With group membership, there is no built in assumption about what permissions are gained (or denied) by being a member of that group.

Roles are similar to groups in that they are represented in the directory by an object. Additionally, roles contain a group of DNs. Roles that are used in access control must have an objectclass of AccessRole.

Pseudo DN

The LDAP directory contains several pseudo DNs. These are used to refer to large numbers of DNs which at bind time share a common characteristic, in relation to either the operation being performed, or the target object on which the operation is being performed.

Currently, three pseudo DNs are defined:

group:cn=anybody

Refers to all subjects, including those that are unauthenticated. All users belong to this group automatically.

group:cn=authenticated

Refers to any DN which has been authenticated to the directory. The method of authentication is not considered.

access-id:cn=this

Refers to the bind Dn which matches the target object's DN on which the operation is performed.

Object filter

This parameter applies to filtered ACLs only. The string search filter as defined in RFC 2254, is used as the object filter format. Because the target object is already known, the string is not used to perform an actual search. Instead, a filter-based compare on the target object in question is performed to determine if a given set of ibm-filterAclEntry values apply to it.

Rights

Access rights can apply to an entire object or to attributes of the object. The LDAP access rights are discrete. One right does not imply another right. The rights may be combined together to provide the desired rights list following a set of rules discussed later. Rights can be of an unspecified value, which indicates that no access rights are 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 is set 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. These are: add an entry, delete an entry, read an attribute value, write an attribute value, 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 a whole. These permissions are add child entries ( a ) and delete this entry ( d ).

The following table summarizes the permissions needed to perform each of the LDAP operations.

Table 11.

Operation	Permission Needed
ldapadd	add (on parent)
ldapdelete	delete (on object)
ldapmodify	write (on attributes being modified)
ldapsearch	search, read (on attributes in RDN) search (on attributes specified in the search filter) search (on attributes returned with just names) search, read (on attributes returned with values)
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 are returned. For returned entries from a search, the subject is required to have search (s) and read (r) access to all the attributes in the RDN of the returned entries or these entries are not returned.

Access Target:

These permissions can be applied to the entire object (add child entry, delete entry), to an individual attribute within the entry, or can be applied to groups of attributes (Attribute Access Classes) as described in the following.

Attributes requiring similar permissions for access are grouped together in classes. Attributes are mapped to their attribute classes in the directory schema file. These classes are discrete; access to one class does not imply access to another class. Permissions are set with regard to the attribute access class as a whole. The permissions set on a particular attribute class apply to all attributes within that access class unless the individual attribute access permissions are specified.

IBM defines three attribute classes that are used in evaluation of access to user attributes: normal, sensitive, and critical. For example, attribute commonName falls into the normal class, and attribute userpassword belongs to the critical class. User defined attributes belong to the normal access class unless otherwise specified.

Two other access classes are also defined: system and restricted. The system class attributes are:

• creatorsName
• modifiersName
• createTimestamp
• modifyTimestamp
• ownerSource
• aclSource

These are attributes maintained by the LDAP server and are read-only to the directory users. OwnerSource and aclSource are described in the Propagation section.

The restricted class of attributes that define the access control are:

• aclEntry
• aclPropagate
• entryOwner
• ownerPropagate
• ibm-filterAclEntry
• ibm-filterAclInherit
• ibm-effectiveAcl

All users have read access to the restricted attributes but only entryOwners can create, modify, and delete these attributes.

Note:

The attribute, ibm-effectiveAcl, is read-only.

EntryOwner

The entry owners have complete permissions to perform any operation on the object regardless of the aclEntry. Additionally, the entry owners are the only ones who are permitted to administer the aclEntries for that object. EntryOwner is an access control subject, it can be defined as individuals, groups or roles.

Note:

The directory administrator is one of the entryOwners for all objects in the directory by default, and the directory administrator's entryOwnership can not be removed from any object.

Propagation

Entries on which an aclEntry has been placed are considered to have an explicit aclEntry. Similarly, if the entryOwner has been set on a particular entry, that entry has an explicit owner. The two are not intertwined, an entry with an explicit owner may or may not have an explicit aclEntry, and an entry with an explicit aclEntry might have an explicit owner. If either of these values is not explicitly present on an 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 an explicitly set value. These values are considered propagated; their values propagate through the directory tree. Propagation of a particular value continues until another propagating value is reached.

Note:

Filter-based ACLs do not propagate in the same way that non-filter-based ACLs do. They propagate to any comparison matched objects in the associated subtree. See Filtered ACLs for more information on the differences.

AclEntry and entryOwner can be set to apply to just a particular entry with the propagation value set to "false", or an entry and its subtree with the propagation value set to "true". Although both aclEntry and entryOwner can propagate, their propagation is not linked in anyway.

The aclEntry and entryOwner attributes allow multi-values, however, the propagation attributes (aclPropagate and ownerPropagate) can only have a single value for all aclEntry or entryOwner attribute values within the same entry.

The system attributes aclSource and ownerSource contain the DN of the effective node from which the aclEntry or entryOwner are evaluated, respectively. If no such node exists, the value default is assigned.

An object's effective access control definitions can be derived by the following logic:

• If there is a set of explicit access control attributes at the object, then that is the object's access control definition.
• If there is no explicitly defined access control attributes, then traverse the directory tree upwards until an ancestor node is reached with a set of propagating access control attributes.
• If no such ancestor node is found, the default access described below is granted to the subject.

Access evaluation

Access for a particular operation is granted or denied based on the subject's bind DN for that operation on the target object. Processing stops as soon as access can be determined.

The checks for access are done by first finding the effective entryOwnership and ACI definition, checking for entry ownership, and then by evaluating the object's ACI values.

Filter-based ACLs accumulate from the lowest containing entry, upward along the ancestor entry chain, to the highest containing entry in the DIT. The effective access is calculated as the union of the access rights granted, or denied, by the constituent ancestor entries. The existing set of specificity and combinatory rules are used to evaluate effective access for filter based ACLs.

Filter-based and non-filter-based attributes are mutually exclusive within a single containing directory entry. Placing both types of attributes into the same entry is not allowed, and is a constraint violation. Operations associated with the creation of, or updates to, a directory entry fail if this condition is detected.

When calculating effective access, the first ACL type to be detected in the ancestor chain of the target object entry sets the mode of calculation. In filter-based mode, non-filter-based ACLs are ignored in effective access calculation. Likewise, in non-filter-based mode, filter-based ACLs are ignored in effective access calculation.

To limit the accumulation of filter-based ACLs in the calculation of effective access, an ibm-filterAclInherit attribute set to a value of "false" may be placed in any entry between the highest and lowest occurrence of ibm-filterAclEntry in a given subtree. This causes the subset of ibm-filterAclEntry attributes above it in the target object's ancestor chain to be ignored.

To exclude the accumulation of filter-based ACLs in the calculation of effective access, an ibm-filterAclInherit attribute set to a value of "false" may be placed in any entry below the lowest occurrence of ibm-filterAclEntry in a given subtree. This causes all ibm-filterAclEntry attributes above it in the target object's ancestor chain to be ignored. The resulting access resolves to the default filter ACL value.

By default, the directory administrator and the master server or the peer server (for replication) get full access rights to all objects in the directory except write access to system attributes. Other entryOwners get full access rights to the objects under their ownership except write access to system attributes. All users have read access rights to system and restricted attributes. These predefined rights cannot be altered. If the requesting subject has entryOwnership, access is determined by the above default settings and access processing stops.

If the requesting subject is not an entryOwner, then the ACI values for the object entries are checked. The access rights as defined in the ACIs for the target object are calculated by the specificity and combinatory rules.

Specificity rule

The most specific aclEntry definitions are the ones used in the evaluation of permissions granted/denied to a user. The levels of specificity are:

• Access-id is more specific than group or role. Groups and roles are on the same level.
• Within the same dnType level, individual attribute level permissions are more specific than attribute class level permissions.
• Within the same attribute or attribute class level, deny is more specific than grant.

Combinatory rule

Permissions granted to subjects of equal specificity are combined. If the access cannot be determined within the same specificity level, the access definitions of lesser specific level are used. If the access is not determined after all defined ACIs are applied, the access is denied.

Note:

After a matching access-id level aclEntry is found in access evaluation, the group level aclEntries are not included in access calculation. The exception is that if the matching access-id level aclEntries are all defined under cn=this, then all matching group level aclEntries are also combined in the evaluation.

In other words, within the object entry, if a defined ACI entry contains an access-id subject DN that matches the bind DN, then the permissions are first evaluated based on that aclEntry. Under the same subject DN, if matching attribute level permissions are defined, they supersede any permissions defined under the attribute classes. Under the same attribute or attribute class level definition, if conflicting permissions are present, denied permissions override granted permissions.

Note:

A defined null value permission prevents the inclusion of less specific permission definitions.

If access still can not be determined and all found matching aclEntries are defined under "cn=this", then group membership is evaluated. If a user belongs to more than one groups, the user receives the combined permissions from these groups. Additionally, the user automatically belongs to the cn=Anybody group and possibly the cn=Authenticated group if the user did an authenticated bind. If permissions are defined for those groups, the user receives the specified permissions.

Note:

Group and Role membership is determined at bind time and last until either another bind takes place, or until an unbind request is received. Nested groups and roles, that is a group or role defined as a member of another group or role, are not resolved in membership determination nor in access evaluation.

For example, assume attribute1 is in the sensitive attribute class, and user cn=Person A, o=IBM belongs to both group1 and group2 with the following aclEntries defined:

1. aclEntry: access-id: cn=Person A, o=IBM: at.attributel:grant:rsc:sensitive:deny:rsc
2. aclEntry: group: cn=group1,o=IBM:critical:deny:rwsc
3. aclEntry: group: cn=group2,o=IBM:critical:grant:r:normal:grant:rsc

This user gets:

• Access of 'rsc' to attribute1, (from 1. Attribute level definition supersedes attribute class level definition).
• No access to other sensitive class attributes in the target object, (from 1).
• 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: sensitive
2. aclEntry: group: cn=group1,o=IBM:sensitive:grant:rsc:normal:grant:rsc

The user has:

• no access to sensitive class attributes, (from 1. Null value defined under access-id prevents the inclusion of permissions to sensitive class attributes from group1).
• and access of 'rsc' to normal class attributes (from 2).

Defining the ACIs and entry owners

The following two examples show an administrative subdomain being established. The first example shows a single user being assigned as the entryOwner for the entire domain. The second example shows a group assigned as the entryOwner.

entryOwner: access-id:cn=Person A,o=IBM 
ownerPropagate: true 
 
entryOwner: group:cn=System Owners, o=IBM 
ownerPropagate: true 
 

The next example shows how an access id "cn=Person 1, o=IBM" is being given permissions to read, search, and compare attribute1. The permission applies to any node in the entire subtree, at or below the node containing this ACI, that matches the "(objectclass=groupOfNames)" comparison filter. The accumulation of matching ibm-filteraclentry attributes in any ancestor nodes has been terminated at this entry by setting the ibm-filterAclInherit attribute to "false".

ibm-filterAclEntry: access-id:cn=Person 1,o=IBM:(objectclass=groupOfNames):
                    at.attribute1:grant:rsc
 
ibm-filterAclInherit: false
 

The next example shows how a group "cn=Dept XYZ, o=IBM" is being given permissions to read, search and compare attribute1. The permission applies to the entire subtree below the node containing this ACI.

aclEntry: group:cn=Dept XYZ,o=IBM:at.attribute1:grant:rsc 
aclPropagate: true 

The next example shows how a role "cn=System Admins,o=IBM" is being given permissions to add objects below this node, and read, search and compare attribute2 and the critical attribute class. The permission applies only to the node containing this ACI.

aclEntry: role:cn=System Admins,o=IBM:object:grant:a:at.
         attribute2:grant:rsc:critical:grant:rsc 
aclPropagate: false

Modifying the ACI and entry owner values

Modify-replace

Modify-replace works the same way as all other attributes. If the attribute value does not exist, create the value. If the attribute value exists, replace the value.

Given the following ACIs for an entry:

aclEntry: group:cn=Dept ABC,o=IBM:normal:grant:rsc 
aclPropagate: true 

perform the following change:

dn: cn=some entry 
changetype: modify 
replace: aclEntry 
aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rsc 
 

The resulting ACI is:

aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rsc 
aclPropagate: true 

ACI values for Dept ABC are lost through the replace.

Given the following ACIs for an entry:

ibm-filterAclEntry: group:cn=Dept ABC,o=IBM:(cn=Manager ABC):normal
                  :grant:rsc 
ibm-filterAclInherit: true 

perform the following changes:

dn: cn=some entry 
changetype: modify 
replace: ibm-filterAclEntry 
ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :grant:rsc 
 
dn: cn=some entry 
changetype: modify 
replace: ibm-filterAclInherit 
ibm-filterAclInherit: false 

The resulting ACI is:

ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                   :grant:rsc 
ibm-filterAclInherit: false 

ACI values for Dept ABC are lost through the replace.

Modify-add

During an ldapmodify-add, if the ACI or entryOwner does not exist, the ACI or entryOwner with the specific values is created. If the ACI or entryOwner exists, then add the specified values to the given ACI or entryOwner. For example, given the ACI:

 aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rsc 

with a modification:

dn: cn=some entry 
changetype: modify 
add: aclEntry 
aclEntry: 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:rsc 
aclEntry: group:cn=Dept ABC,o=IBM:at.attribute1:grant:rsc 

For example, given the ACI:

Ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :grant:rsc 

with a modification:

dn: cn=some entry 
changetype: modify 
add: ibm-filterAclEntry 
ibm-filterAclEntry: group:cn=Dept ABC,o=IBM:(cn=Manager ABC)
                  :at.attribute1:grant:rsc 

would yield an multi-valued aclEntry of:

Ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :grant:rsc
ibm-filterAclEntry: group:cn=Dept ABC,o=IBM:(cn=Manager ABC):at.attribute1
                  :grant:rsc

The permissions under the same attribute or attribute class are considered as the basic building blocks and the actions are considered as the qualifiers. If the same permission value is being added more than once, only one value is stored. If the same permission value is being added more than once with different action values, the last action value is used. If the resulting permission field is empty (""), this permission value is set to null and 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 entry 
changetype: modify 
add: aclEntry 
aclEntry: 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:grant:r 
 

For example, given the following ACI:

Ibm-filterAclEntry: group:cn=Dept XYZ,O=IBM:(cn=Manager XYZ):normal
                  :grant:rsc 

with a modification:

dn: cn=some entry 
changetype: modify 
add: ibm-filterAclEntry 
ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :deny:r:critical:deny::sensitive:grant:r

yields an aclEntry of:

ibm-filterAclEntry: group:cn=Dept XYZ,O=IBM:(cn=Manager XYZ):normal
                  :grant:sc:normal:deny:r:critical:grant::sensitive
                  :grant:r 

Modify-delete

To delete a particular ACI value, use the regular ldapmodify-delete syntax.

Given an ACI of:

aclEntry: group:cn=Dept XYZ,o=IBM:object:grant:ad 
aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rwsc 
 
dn: cn = some entry 
changetype: modify 
delete: aclEntry 
aclEntry: group:cn=Dept XYZ,o=IBM:object:grant:ad 

yields a remaining ACI on the server of :

aclEntry: group:cn=Dept XYZ,o=IBM:normal:grant:rwsc 
 

Given an ACI of:

ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):object
                  :grant:ad 
ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :grant:rwsc 
      
dn: cn = some entry 
changetype: modify 
delete: ibm-filterAclEntry 
ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):object
                  :grant:ad 

yields a remaining ACI on the server of:

ibm-filterAclEntry: group:cn=Dept XYZ,o=IBM:(cn=Manager XYZ):normal
                  :grant:rwsc 

Deleting an ACI or entryOwner value that does not exist results in an unchanged ACI or entryOwner and a return code specifying that the attribute value does not exist.

Deleting the ACI/entry owner values

With the ldapmodify-delete operation, the entryOwner can be deleted by specifying

dn: cn = some entry 
changetype: modify 
delete: entryOwner 
 

In this case, the entry would then have no explicit entryOwner. The ownerPropagate is also removed automatically. This entry would inherit its entryOwner from the ancestor node in the directory tree following the propagation rule.