| Note |
|---|
|
Before using this information and the product it supports, read the general information under Appendix D, Notices. |
First Edition (April 2002)
This edition applies to version 4, 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.
This document contains the information that you need to administer the IBM Directory Server.
A directory is a collection of information about objects arranged in some order that gives details about each object. It is a specialized database, that stores typed and ordered information about objects. Directories enable 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 that 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.
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).
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 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:
The preferred method of administering the server is by using the Server Administration GUI. Because the Linux and HP-UX operating systems do not support Server Administration, if you are using either of those operating systems, you must use the command line alternatives that are provided for the various tasks.
If you have previously set the administrator Distinguished Name (DN) and password, and configured a Web server, you can start the Server Administration GUI from a Web browser.
After the tool has been started, the application window has three parts:
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 slapd32.conf file:
DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configuration ibm-slapdDbName: <databasename> ibm-slapdUserID: <username> ibm-slapdDbUserPW: <password> ibm-slapdDbInstance: <username>
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:
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. Following are further examples of distinguished names 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
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:
CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB
This is the preferred method.
"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 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:
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".
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.
This DN refers to any dn that has been authenticated by the directory. The method of authentication is not considered.
Some examples of pseudo DNs:
access-id: cn = this:critical:rwsc AclEntry: group: cn=Anybody: normal:rsc AclEntry: group: cn=Authenticated: sensitive:rcs
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
| 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.
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:
| 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").
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.
The following tasks can be performed by the directory administrator:
The administrator name and password is usually set during the server configuration process. However, you can create an administrator name and an administrator password by using either the ldapcfg command or the ldapxcfg utility.
Using the ldapcfg command:
ldapcfg -u <admindn> -p <adminpassword>
To use the ldapxcfg utility type ldapxcfg on a command line. When the utility panel is displayed check Set the directory administrator name and password and follow the directions. See the Installation and Configuration Guide for additional information on using the ldapxcfg utility.
See Distinguished names (DNs) for more information about distinguished names.
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:
After the server is configured and re-started, 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, 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 Server Administration, you can select one of the following four encryption options:
The default option is imask. After a configuration change, the directory server must be re-started to activate the change. 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\slapd32.conf
It is also possible (but not recommended) to modify the configuration file using an editor.
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.
Notes:
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.
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.
To create or add a suffix use one of the following methods.
If you have not done so already, click the arrow to the left of Settings in the navigation area.
To create a suffix, add the following line ibm-slapdSuffix: <suffixname> to the slapd32.conf file stanza:
DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configuration ibm-slapdDbName: <databasename> ibm-slapdUserID: <username> ibm-slapdDbUserPW: <password> ibm-slapdDbInstance: <username> ibm-slapdSuffix: <suffixname>
You must restart the server for the change to take effect.
To remove a suffix use one of the following methods:
If you have not done so already, click the arrow to the left of Settings in the navigation area.
To delete a suffix, remove the line from the slapd32.conf file. For example, the following line ibm-slapdSuffix: <suffixname> to the slapd32.conf file stanza:
DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configuration ibm-slapdDbName: <databasename> ibm-slapdUserID: <username> ibm-slapdDbUserPW: <password> ibm-slapdDbInstance: <username> ibm-slapdSuffix: <suffixname>
You must restart the server for the change to take effect.
To verify current condition of the server use one of the following methods:
If you have not done so already, click the arrow to the left of Current state in the navigation area, then click Server status. If the server is running, the following information is displayed:
day month date hour:minutes:seconds timezone year
day month date hour:minutes:seconds timezone year
ldapsearch -h <servername> -p <portnumber> -b cn=monitor -s base objectclass=*
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 need 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.
The administrator can tell if indexing has been enabled for an attribute by looking at the attribute definition in the Directory Management Tool, or by looking at the attribute definition returned by a search of cn=schema. When viewing an attribute definition in the Directory Management 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 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 slapd32.conf file. 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 slapd32.conf file. If the line does not exist, add it with a value of TRUE to allow non-Administrator bind.
dn: cn=Configuration cn: Configuration ibm-slapdAdminDn: <adminname> ibm-slapdAdminPW: <password> ibm-slapdErrorLog: <errorlogfile> ibm-slapdPort: <poprtnumber> ibm-slapdSizeLimit: <sizelimit> ibm-slapdTimeLimit: <timelimit> ibm-slapdSortSrchAllowNonAdmin: TRUE ibm-slapdSortKeyLimit: 3
You must restart the server for any changes to take effect.
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:
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 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.
dn: cn=Configuration cn: Configuration ibm-slapdAdminDn: <adminname> ibm-slapdAdminPW: <password> ibm-slapdSizeLimit: <sizelimit> ibm-slapdTimeLimit: <timelimit> ibm-slapdPagedResAllowNonAdmin: TRUE
You must restart the server for any changes to take effect.
dn: cn=Configuration cn: Configuration ibm-slapdAdminDn: <adminname> ibm-slapdAdminPW: <password> ibm-slapdSizeLimit: <sizelimit> ibm-slapdTimeLimit: <timelimit> ibm-slapdPagedResLmt: 4
You must restart the server for any changes to take effect.
dn: cn=Configuration cn: Configuration ibm-slapdAdminDn: <adminname> ibm-slapdAdminPW: <password> ibm-slapdSizeLimit: <sizelimit> ibm-slapdTimeLimit: <timelimit> ibm-slapdPagedSizeLmt: 40
You must restart the server for any changes to take effect.
dn: cn=Configuration cn: Configuration ibm-slapdAdminDn: <adminname> ibm-slapdAdminPW: <password> ibm-slapdSizeLimit: <sizelimit> ibm-slapdTimeLimit: <timelimit> ibm-slapdIdleTimeOut: 180
You must restart the server for any changes to take effect.
The LDAP server returns all referrals to the client at the end of a search request, the same as is done today. 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 (this actually means the application using the client - but to the server it is still the client) 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.
To set the performance settings manually you must edit the slapd32.conf file.
To set the maximum number of entries that a search returns and the maximum amount of time the server spends processing a request (in seconds) modify the entries highlighted in bold in the initial stanza cn=Configuration . This example uses the default settings.
dn: cn=Configuration
cn: Configuration
ibm-slapdAdminDn: cn=root
ibm-slapdAdminPW: >1Ex7zvuIMihVY+WCWxkJeU6JdnYG0lnLIvNE6THzSJir4Q6Rzyr5oxU
iwv8cZjS6qoKExlLlvQGNIFGV5RePwkB/D382sQYx34zUJxDkJfr1B4c
Ematpbu5eQAi4I1JtNTfxO2chSQRhoQednv/9AvF77p+7s7DlJq<
ibm-slapdErrorLog: /tmp/slapd.errors
ibm-slapdPort: 389
#ibm-slapdPwEncryption must be one of none/imask/crypt/sha
ibm-slapdPwEncryption: imask
ibm-slapdSizeLimit: 500
#ibm-slapdSysLogLevel must be one of l/m/h (l=terse, h=verbose)
ibm-slapdSysLogLevel: m
ibm-slapdTimeLimit: 900
objectclass: top
objectclass: ibm-slapdTop
To set the number of DB2 connections used by the server modify the entry highlighted in bold in the stanza dn: cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration.
dn: cn=Directory, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration
cn: Directory
ibm-slapdDbConnections: 15
ibm-slapdDbInstance: ldapdb2
ibm-slapdDbLocation: C:
ibm-slapdDbName: ldapdb2
ibm-slapdDbUserId: ldapdb2
ibm-slapdDbUserPW: >1dBKs26P8vD5nK+dDOT+OBpZ0TNdlfvhD2sOzCjITaFXVaN4E3l4DkucG
srQ6ulr1h0cClbN9uqrehllRVitB+J1OWPANCMezC27wOidzJHw6i0l0gy
IBf80pVs/qGpdAjpDoZDGNZpptEboU9uNdIJsZgCGN9lS7e<
ibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_init
ibm-slapdPlugin: preoperation /bin/libcl.dll CLInit cn=changelog
ibm-slapdReadOnly: FALSE
ibm-slapdSuffix: cn=localhost
ibm-slapdSuffix: o=ibm, c=us
objectclass: top
objectclass: ibm-slapdRdbmBackend
You can use either method to start or stop the server. However, you cannot combine the methods. If you start the server using Server Administration, you must use Server Administration to stop the server. Do not use the command line method to stop the server if you have used Server Administration to start it.
Use the following commands to start and stop the server on UNIX platforms:
slapd
ps -ef | grep slapd
kill -9 `cat /etc/slapd.pid `
Notes:
cat / etc/slapd.pid
For Windows systems:
Use the following tasks to administer your DB2 database:
If you need to change or update the settings of your database, perform the following:
If you have not done so already, click the arrow to the left of Database in the navigation area.
The DB2 database used by the IBM Directory has settings that can be tuned to improve performance or to address errors reported by DB2 indicating a resource that needs to be increased. The DB2 errors contain the name of the parameter to be reset (but does not recommend a value). Before changing any of these parameters, it is important to record the default settings in case you need to restore these settings. See the IBM Directory Server Version 4.1 Tuning Guide for the recommended settings.
To get the current DB2 parameter settings:
su - ldapdb2
db2start
db2 get db cfg for ldapdb2 |tee ldapdb2.cfg.orig
You can find the DB2 configuration information in the ldapdb2.cfg.orig file.
To reset a DB2 parameter (for example, APPLHEAPSZ):
su - ldapdb2
db2start
db2 update db cfg for ldapdb2 using APPLHEAPSZ 256
kill -9 `cat /etc/slapd.pid` db2 force application all
slapd
Although the server can now run, the directory does not contain any data. To add data do one of the following.
If you have not done so already, click the arrow to the left of Database in the navigation area.
You can define a suffix by editing the /usr/ldap/etc/slapd32.conf file. You can add data in numerous ways. This example imports an LDIF file containing sample data rooted at the suffix 'o=ibm,c=us'.
dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,
cn=Configuration
...
ibm-slapdDbUserPW: ******
ibm-slapdSuffix: o=ibm,c=us
cn: Directory
See Understanding suffixes for additional information.
ldif2db -i /usr/ldap/examples/sample.ldif
Use either of the following methods to back up your database.
Notes:
If you have not done so already, click the arrow to the left of Database in the navigation area.
To back up the directory, use the following commands:
su - ldapdb2 db2 backup database ldapdb2 to </a/big/filesystem/backup>
db2cmd db2 backup database ldapdb2 to </a/big/filesystem/backup>
backup database ldapdb2 to </a/big/filesystem/backup>
If you need to replace your existing database with one that has been previously backed up, stop the server and do either of the following:
If you have not done so already, click the arrow to the left of Database in the navigation area.
Issue the following command:
db2 restore database ldapdb2 from </a/big/filesystem/backup> replace existing
You can export database entries to an LDIF file.
If you have not done so already, click the arrow to the left of Database in the navigation area, then click Export LDIF.
Use the db2ldif command to export database entries:
db2ldif -o /temp/<directory>.ldif
where:
You can also use the -s option, if you want to export entries with a specific suffix. The default is to export all the entries.
After a significant amount of update activity on a directory, you might need to use the DB2 maintenance utilities to free up unused disk space and to make the queries more efficient. Optimizing the DB2 database updates the statistics to improve performance and query speed.
If you have not done so already, click the arrow to the left of Database in the navigation area.
The IBM Directory Server includes a runstats utility that updates the database statistics. This utility is located in the usr/ldap/sbin directory on UNIX systems and in the <ldap installation directory>\bin directory on Windows systems. To update the statistics using the command line issue the following command:
runstats
Additionally you can use the reorgchk utility periodically to see if you have DB2 tables that need to be reorganized.
kill -9 `cat /etc/slapd.pid` db2 reorgchk update statistics on table all
Doing RUNSTATS .... Table statistics: F1: 100*OVERFLOW/CARD < 5 F2: 100*TSIZE / ((FPAGES-1) * (TABLEPAGESIZE-76)) > 70 F3: 100*NPAGES/FPAGES > 80 CREATOR NAME CARD OV NP FP TSIZE F1 F2 F3 REORG ------------------------------------------------------------------------------- LDAPDB2 ABSTRACT - - - - - - - - --- LDAPDB2 ACLPERM 2 0 1 1 138 0 - 100 --- LDAPDB2 ACLPROP 2 0 1 1 40 0 - 100 --- LDAPDB2 ADDITIONAL 150600 0 5043 5043 20180400 0 99 100 *-* LDAPDB2 ADDRESS1 709 0 15 15 58847 0 100 100 --- ... etc ...
The *-* characters in the REORG column indicate that a table needs to be reorganized. You can do this with the reorg command. For the given example issue the command:
db2 reorg table LDAPDB2.ADDITIONAL
IBM Directory supports a wide variety of national language characters through the UTF-8 (UCS Transformation Format) character set. As specified for the LDAP Version 3 protocol, all character data that is passed between an LDAP client and a server is in UTF-8. Consequently, the directory server can be configured to store any national language characters that can be represented in UTF-8. The limitations on what types of characters can be stored and searched for are determined by how the database is created. The database character set can be specified as "UTF-8" or it can be allowed to default to the server system's local character set (based on the locale, language, and code page environment).
If you specify UTF-8, you can store any UTF-8 character data in the directory. LDAP clients running anywhere in the world (in any UTF-8 supported language) can access and search the directory. In many cases, however, the client has limited ability to properly display the results retrieved from the directory in a particular language/character set.
A UTF-8 database has a fixed collation sequence. That sequence is the binary order of the UTF-8 characters. It is not possible to do language-sensitive collation with a UTF-8 database.
If it is important to your LDAP applications or users to get results for a search using an ordering filter (for example, "name >= SMITH") or any search specifying the control to sort the results, as they would expect for their native language, then UTF-8 might not be the appropriate character set for their directory database. In that instance, the LDAP server system and all client systems should run using the same character set and locale. For example, an LDAP server running in a "Spanish" locale with a database created using that locale returns results of searches based on character ordering, as Spanish-language clients would expect. This configuration does limit your directory user community to a single end-user character set and collation sequence.
If you wish to create your own database using the UTF-8 character set and configure it as a custom database for your directory, you can do the following:
Open a DB2 Command Line Processor window. Enter the following command at the db2 => command prompt:
CREATE DATABASE <databasename> USING CODESET UTF-8 TERRITORY US
Remember to update the following stanza in the slapd32.conf file with your actual database name.
DN: cn=Directory cn=RDBM Backends cn=IBM SecureWay cn=Schemas cn=Configuration ibm-slapdDbName: <databasename> ibm-slapdUserID: <username> ibm-slapdDbUserPW: <password> ibm-slapdDbInstance: <username>
The IBM Directory supports the following Internet Assigned Number Authority
(IANA) character set names by platform:
| Character | Locale | DB2 Code Page | ||||
| Set Name | Linux, Linux_390, HP-UX | NT | AIX | Solaris | UNIX | NT |
| ISO-8859-1 | X | X | X | X | 819 | 1252 |
| ISO-8859-2 | X | X | X | X | 912 | 1250 |
| ISO-8859-5 | X | X | X | X | 915 | 1251 |
| ISO-8859-6 | X | X | X | n/a | 1089 | 1256 |
| ISO-8859-7 | X | X | X | n/a | 813 | 1253 |
| ISO-8859-8 | X | X | X | n/a | 916 | 1255 |
| ISO-8859-9 | X | X | X | n/a | 920 | 1254 |
| IBM437 | n/a | X | n/a | n/a | 437 | 437 |
| IBM850 | n/a | X | X | n/a | 850 | 850 |
| IBM852 | n/a | X | n/a | n/a | 852 | 852 |
| IBM857 | n/a | X | n/a | n/a | 857 | 857 |
| IBM862 | n/a | X | n/a | n/a | 862 | 862 |
| IBM864 | n/a | X | n/a | n/a | 864 | 864 |
| IBM866 | n/a | X | n/a | n/a | 866 | 866 |
| IBM869 | n/a | X | n/a | n/a | 869 | 869 |
| TIS-620 | n/a | X | X | n/a | 874 | 874 |
| EUC-JP | X | n/a | X | X | 954 | n/a |
| EUC-KR | n/a | n/a | X | X | 970 | n/a |
| EUC-CN | n/a | n/a | X | X | 1383 | n/a |
| EUC-TW | n/a | n/a | X | X | 964 | n/a |
| Shift-JIS | X | X | X | X | 932 | 943 |
| KSC | n/a | X | n/a | n/a | n/a | 949 |
| GBK | n/a | X | X | n/a | 1386 | 1386 |
| Big5 | n/a | X | X | X | 950 | 950 |
Manual creation of an LDIF file containing UTF-8 values is difficult. To simplify this process, a charset extension to the LDIF format is supported. This extension allows an IANA character set name to be specified in the header of the LDIF file (along with the version number). A limited set of the IANA character sets are supported.
You can use the optional charset tag so that the server utilities automatically convert from the specified character set to UTF-8 as in the following example:
version: 1 charset: ISO-8859-1 dn: cn=Juan Griego, o=University of New Mexico, c=US cn: Juan Griego sn: Griego description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvd title: Associate Dean title: [title in Spanish] jpegPhoto:< file:///usr/local/photos/jgriego.jpg
In this instance, all values following an attribute name and a single colon are translated from the ISO-8859-1 character set to UTF-8. Values following an attribute name and a double colon (such as description:: V2hhdCBhIGNhcm... ) should be base 64-encoded, and are expected to be either binary or UTF-8 character strings. Values read from a file, such as the jpegPhoto attribute specified by the URL in the example above, are also expected to be either binary or UTF-8. No translation from the specified "charset" to UTF-8 is done on those values.
In this example of an LDIF file without the charset tag, content is expected to be in UTF-8:
# IBM IBM Directorysample LDIF file # # The suffix "o=IBM, c=US" should be defined before attempting to load # this data. version: 1 dn: o=IBM, c=US objectclass: top objectclass: organization o: IBM dn: ou=Austin, o=IBM, c=US ou: Austin objectclass: organizationalUnit seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US
This same file could be used without the version: 1 header information, as in previous releases of the IBM Directory:
# IBM IBM Directorysample LDIF file # #The suffix "o=IBM, c=US" should be defined before attempting to load #this data. dn: o=IBM, c=US objectclass: top objectclass: organization o: IBM dn: ou=Austin, o=IBM, c=US ou: Austin objectclass: organizationalUnit seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US
You can configure the directory server to use the default DB2 database or use an existing DB2 database of your own.
To configure the directory server to use the default DB2 database:
To configure the directory server to use an existing DB2 database of your own:
You must tell the server to use the database that you created. Scroll down to the last entry in the slapd32.conf file and insert the lines indicated in bold type before 'cn: Directory':
dn: cn=Directory,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration objectclass: top objectclass: ibm-slapdRdbmBackend ibm-slapdDbInstance: ldapdb2 ibm-slapdDbName: ldapdb2 ibm-slapdDbUserId: ldapdb2 ibm-slapdDbUserPW: <password> cn: Directory
where ldapdb2 is the name of your database and <password> is the password you set when you created the database.
Replication is a technique used by directories to improve performance, reliability, or both. The replication process keeps multiple directories synchronized.
There are several benefits realized through replication. The largest benefit is providing a means of faster searches. Instead of having all search requests directed at a single server, the search requests can be spread among several different servers. This improves the response time for the request completion.
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 a
master-slave replication model. There are three types of
directories: masters, replicas and
peers. The IBM Directory refers to the master as the
master server. The replicas are referred to as replica
servers.
Table 4. Master-replica server definitions
| Master | The master server contains the master directory information from where updates are propagated to the replicas. All changes are made and occur on the master server, and the master is responsible for propagating these changes to the replicas (slaves). |
| Replica | An additional server that contains a directory replica. The replicas must be exact copies of the master. The replica provides a backup to the master server. Even if the master server crashes, or is unreadable, the replica can still fulfill search requests and provide access to the data. |
| Peer-to-peer | Peer replication is a replication 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. |
Normally only one master server is allowed, except in peer-peer replication (see Using peer-to-peer replication). Replicas cannot serve as masters to other replicas. You can request some types of updates on a replica server, but the update is actually forwarded to the master server and made there. 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 you are no longer using a replica, you must remove its definition from the master server. Leaving the definition causes the server to queue up all updates and use unnecessary directory space. Also, the master server continues trying to contact the missing replica to retry sending the data.
Use the following procedures to add replica servers.
If a change is made to the master, the change is not sent to the replicas for the time specified by the replica update interval. When the Update interval time elapses, this change and all other accumulated changes (changes made during the interval) are replicated. Any changes made during the time that the master is replicating are also replicated. After the master replicates all pending changes, it waits for new changes. When the master receives a new change, it waits for the specified update interval before replicating the new change.
To add a replica server you can use the ldapmodify command.
ldapmodify -c -V 3 -D <admindn> -w <adminpw> -f myschema.ldif
where the myschema.ldif file contains minimally the required attributes (highlighted in bold in this example):
dn: cn=replica_1, cn=localhost changetype: add objectclass: replicaObject cn: replica_1 replicaHost: ldapaixtaa.austin.ibm.com replicaBindDn: cn=Blade Runner replicaCredentials: replicant replicaPort: 389 replicaBindMethod: Simple replicaUseSSL: FALSE replicaUpdateTimeInterval: 0 description: replica object added by 15134 S3LDSM00.pl
See also 2a.
If an interruption occurs during replication use the following procedures to verify whether the replicas are synchronized with the master:
To test if all replicas are synchronized to the master server:
Replication is synchronized for all replicas if the master's ldapdb2.change table has 0 rows. This means that replication is complete at the time the command was issued.
To test if a given replica is synchronized to the master server:
For example <replica dn> might be: 'cn=replica1, cn=localhost'
A given replica is synchronized with the master if the number of rows in the master's ldapdb2.progress table (where prg = the dn of the replica object of the given replica ) is equal to the number of rows in the masters ldapdb2.change table. This means that replication is complete for the given server at the time the command was issued.
If one or more of the replicas are out of synchronization, use the following steps to synchronize all of the replicas.
If your replicas are not synchronized with the master you might want to do the following to clean the change table.
db2 select id from change fetch first 1 row only
db2 "delete from ldapdb2.change where (id = X)"
where X is the id determined in the previous step. After the entry is deleted from the change table and the master server is restarted, the entry is not replicated.
Notes:
The main concern is to prevent any updates to the directory while the data is being added to the master. There are several different ways to configure your master and replica. Two methods are presented in the following.
If you have not done so already, click the arrow to the left of Replication in the navigation area, then click Settings.
Use the following procedures to configure replicas manually.
The simple configuration has fewer steps than the other method presented, but it can be slower for large directories and can be used only when the master directory is initially loaded. Use General configuration when you are adding a replica to a master that is already loaded with data.
The following information must be added to the directory on the master.
dn: cn=myreplica,cn=localhost cn: myreplica objectClass: replicaObject objectClass: top replicaHost: myreplica.mycompany.com replicaBindDn: cn=master replicaCredentials: master2pass replicaPort: 389 replicaBindMethod: Simple replicaUseSSL: FALSE replicaUpdateTimeInterval: 0
ldapadd -D cn=admin -w admin2pass -c -d<debuglevel> -f myreplica.ldif
The advantage of this method is that the replica can be added without having to stop and restart the master.
dn: cn=Master Server,cn=Configuration objectclass: top objectclass: ibm-slapdReplication cn: Master Server ibm-slapdMasterPW: masterpass2 ibm-slapdMasterDN: cn=master ibm-slapdMasterReferral: ldap://mymaster.mycompany.com
If you use ldapadd, the server is running. When the data is loaded onto the master, the master begins replicating it to all of the replica servers.
If you use ldif2db to load the data, you must first stop the server. After the data has completed loading on the master, restart the master server . This causes the master to replicate the data onto all of the replicas. It is very important that you restart the master server after you have added entries and before defining any additional replicas, or the master and new replica can become out-of-synchronization.
It is not necessary to restart the master server, if you use ldapadd to add entries.
Your IBM Directory configuration is ready for use. You do not need to wait until all of the data has finished replicating onto your replica servers before using the IBM Directory. However, not all data will be present on your replica servers until the process is complete, so your searches might return incomplete or missing data.
The general configuration is used when you need to add a new replica server after the master server has had data loaded onto it. It can also be used to reload data onto a replica that becomes out of synchronization with the master.
If this is a new replica, skip to step 5:
DB2 backup and restore provide an alternate way of creating a replica that is faster than using db2ldif and ldif2db or bulkload, especially with large directories.
There are two ways to use DB2 utilities to populate, or re-synchronize, the directory for a replica. If you already have a replica, you can copy its directory and leave the master server running. You can also copy the directory of the master server.
To copy from a replica:
su - ldapdb2
db2 backup database ldapdb2 to /a/big/filesystem/backup
su - ldapdb2
db2 restore database ldapdb2 from /a/big/filesystem/backup replace existing
Use the same file system name used for the backup.
To copy from a master:
su - ldapdb2
db2 backup database ldapdb2 to /a/big/filesystem/backup
Specify a file system with enough free space for the backup. Give only the path name. DB2 will name the backup files based on a timestamp.
su - ldapdb2
db2 restore database ldapdb2 from /a/big/filesystem/backup replace existing
Use the same file system name used for the backup.
The master server uses the database tables named change and progress to coordinate replication. These tables are dropped and the directory entries for replica objects are ignored on the new replica.
Use the following procedures to list the replica servers.
If you have not done so already:
The replicas and their attributes are listed in the work area.
Use the ldapsearch command to list the replicas. For example:
ldapsearch --h mymaster --D cn=admin --w admin2pass --b cn=localhost "objectClass=replicaobject"
Use the following procedures to edit a replica server.
Use the ldapmodify command to edit the replica object in the master's directory. For example, to change the password that the master uses with the replica servers, issue the following command:
ldapmodify -h anymaster -v -D cn=admin -w admin2pass -f mymod.ldif
where the mymod.ldif file contains the following information:
dn: cn=myreplica,cn=localhost replicaCredentials: new2pass
Use the following procedures to remove replica servers.
Use the ldapdelete command to remove a replica from the directory. For example:
ldapdelete --h mymaster -v --D cn=admin --w admin2pass "cn=myreplica, cn=localhost"
where "cn=myreplica, cn=localhost" is the DN of the replica that you want to delete.
After the replica is removed, no update information is sent to that replica.
Peer replication is a replication 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.
At startup, a server queries the database to determine if there are any replica objects. These objects define replica or peer servers for this particular server. The schema definition for these objects describes how a server can locate and connect to the replica or peer server, as well as other replication properties.
Within the slapd32.conf file there are currently several parameters relating to replication. If an ibm-slapdMasterServerDn and ibm-slapdMasterServerPW are specified, this server is presumed to be a read-only replica. The ibm-slapdMasterServerDn and ibm-slapdMasterServerPW in the slapd32.conf file must match the replicaBindDn and replicaCredentials in the replica object definition found on the master server.
A peer server is designated in the slapd32.conf file with the attributes ibm-slapdPeerDn and ibm-slapdPeerPW in the cn=Master,cn=Configuration object.
A server can be either a replica server or a peer server, it can not be both. That means that the ibm-slapdMasterServerDn parameter in the slapd32.conf file is mutually exclusive with the ibm-slapdPeerDn configuration file attribute. If both are defined in the slapd32.conf file, the server does not start and the following message is logged in the slapd.errors file:
Can not specify both masterServerDn and peerDn
Machine 1 listens on port 389 and is a peer server of machine 2. If the entry dn: cn=Master Server, cn=Configuration is already present in the slapd32.conf file, start the server, turn off replication, and stop the server before proceeding. Otherwise, add the following section to the slapd32.conf file on machine 1:
dn: cn=Master Server, cn=Configuration cn: Master Server ibm-slapdPeerDn: cn=peer ibm-slapdPeerPW: <machine2password> objectclass: ibm-slapdReplication objectclass: top
A replica object is added to the machine 1 database through the following ldif file:
dn: cn=machine2, cn=localhost cn: machine2 objectclass: replicaObject replicabindDN: cn=peer replicaCredentials: <machine2password> replicaPort: 389 replicaHost: machine2.<fully-qualified-hostname>
Machine 2 listens on port 389 and is a peer server of machine 1. If the entry dn: cn=Master Server, cn=Configuration is already present in the slapd32.conf file, start the server, turn off replication, and stop the server before proceeding. Otherwise, add the following section to the slapd32.conf file on machine 2:
dn: cn=Master Server, cn=Configuration cn: Master Server ibm-slapdPeerDn: cn=peer ibm-slapdPeerPW: <machine1password> objectclass: ibm-slapdReplication objectclass: top
A replica object is added to the machine 2 database through the following ldif file:
dn: cn=machine1, cn=localhost cn: machine1 objectclass: replicaObject replicabindDN: cn=peer replicaCredentials: <machine1password> replicaPort: 389 replicaHost: machine1.<fully-qualified-hostname>
Updates that are received from peer servers are not propagated to any other replica or peer server definitions. When an update is received by a peer server, the update is applied to the database. If the update was received from a peer server, the update is applied and processing stops. If the update was made by another client, the directory is updated, and the update information is propagated to the other peers and replicas. Because peer servers do not propagate updates to other replica definitions, do not configure peer servers as master servers in a master-slave style replication.
The peer Dn ID is given the same level of permission as the master DN. Guard the peer DN ID and password carefully.
The Directory Information Tree object cn=Master Server, cn=Configuration supports two additional optional attributes:
Referrals provide a way for servers to refer clients to additional directory servers. With referrals you can:
Some of the advantages of using referrals are the ability to:
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.
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.
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.
To associate servers through referrals:
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: o=IBM,c=US objectclass: referral ref: ldap://9.130.25.51:389/o=IBM,c=US
Define a default referral to reference a directory on another server. The default referral can be used to point to:
# 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>
To remove a default referral, you need to remove or comment out the appropriate line that contains the ldap identifier and the hostname:port information in the slapd32.conf file. For example:
# 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>
When performing searches, the same DN that was used to bind 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.
Following are the steps involved in distributing the namespace using referrals.
country - US company - IBM, Lotus organizationalUnit - IBM Austin, IBM Endicott, IBM Raleigh, IBM HQ
Figure 2. Setting up the servers
Server descriptions:
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.
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
The change log records changes (such as schema and entry changes) in the typical LDAP entry structure that can be retrieved through the LDAP API. The change log enables an IBM Directory client application to retrieve a set of changes that have been made to an IBM Directory server database. The client (which might be another IBM Directory server) might then update its own replicated or cached copy of the data.
Because the IBM Directory schema can be changed, it is possible to have any modifications to the schema logged to the change log. Each configuration combination requires different entries in the slapd32.conf file.
You can use the ldapxcfg or ldapcfg utilities, to automatically create a change log database. Using the ldapxcfg utility, select Create a default directory DB2 database and select Create a database for change log support. Using the ldapcfg command, specify the -g option when configuring your database.
ldapcfg -l /home/ldapdb2 -o -g
See your Installation and Configuration Guide for more information.
Before you configure the change log you must identify the suffix that it uses. In the following examples, the suffix for the change log is "cn=changelog". Note that this suffix can be changed.
After creating the change log database, you must ensure that it has the correct access rights set and configured correctly.
The following instructions assume that the default LDAP install and configuration parameters were used to configure the directory database, and that the change log database name is "ldapclog".
For UNIX systems, use the db2 command shell to perform the following commands. These commands assume that the user is logged in as 'root'.
su - ldapdb2
db2 create database ldapclog on /home/ldapdb2 using codeset UTF-8 territory US
db2 update database configuration for ldapclog using DBHEAP 500
For Windows systems, use the DB2 Control Center to perform the following commands. These commands assume that the user is logged in as a user that can administer DB2.
To manually create the change log, the following must be added to the slapd32.conf file:
dn: cn=Change Log, cn=RDBM Backends, cn=IBM SecureWay, cn=Schemas, cn=Configuration cn: Change Log cn: changelog ibm-slapdChangeLogMaxEntries: 0 ibm-slapdDbConnections: 2 ibm-slapdDbInstance: ldapdb2 ibm-slapdDbName: ldapclog ibm-slapdDbUserId: ldapdb2 ibm-slapdDbUserPW: ldapdb2 ibm-slapdPlugin: database /lib/libback-rdbm.so rdbm_backend_init ibm-slapdPlugin: preoperation /usr/ldap/lib/libibmcl.so CLInit cn=changelog ibm-slapdReadOnly: FALSE ibm-slapdSuffix: cn=changelog ibm-slapdUseProcessIdPw: FALSE ibm-slapdDbAlias: ldapclgb objectClass: top objectClass: ibm-slapdRdbmBackend
Notes:
The IBM Directory slapd32.conf file contains a stanza that defines schema configuration. For example:
dn: cn=SchemaDB,cn=LDCF Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration objectclass: top objectclass: ibm-slapdLdcfBackend cn: SchemaDB ibm-slapdSuffix: cn=schema
To enable schema updates to be shadowed to the change log, the preceding stanza is changed to:
dn: cn=SchemaDB,cn=LDCF Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration objectclass: top objectclass: ibm-slapdLdcfBackend cn: SchemaDB ibm-slapdPlugin: database /bin/libcl.dll CLInit cn=changelog ibm-slapdSuffix: cn=schema
Note the additional line. The last parameter in this line, "cn=changelog" tells the IBM Directory server which change log database it must log schema changes to. Configuration of this change log database is discussed in the next section. For AIX operating systems, replace .dll to .a in the library names.
The IBM Directory logs changes to a separate database. Besides the database that holds the actual data, changelog uses another database to store changes. In the change log stanza of the slapd32.conf file, the name of the second database is ldapclog:
dn: cn=Change Log,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration objectclass: top objectclass: ibm-slapdRdbmBackend cn: Directory ibm-slapdPlugin: database /lib/libback-rdbm.sl rdbm_backend_init ibm-slapdSuffix: cn=changelog ibm-slapdDbName: ldapclog ibm-slapdDbUserPW: <db2userpw> ibm-slapdDbUserID: db2user
Notes:
The change log can be accessed through normal mechanisms as the primary tree. However, the directory entry the client binds as does not exist in the change log directory tree. This is more a statement of policy, because the entry can exist in the change log database. Administration of the changelog database is easier, however, if no bind entries are contained in it.
After entries that are allowed to access the change log are identified, the ACLs for the root level of the change log tree need to be changed (to enable users to have full read, search and compare privileges for the tree or subtree). Do not configure anonymous access for your change log tree, do not grant write or delete access to the tree. This needs to be done separately for each change log database in the system.
You can limit the number of entries the change log can hold by using the "changelogmaxentries <integer>" value, which is the maximum number of entries in the change log that can be set. The values can be 0 to the maximum integer. This value is defined in the Changelog entry where the change log database is defined: .
dn: cn=Change Log,cn=RDBM Backends,cn=IBM SecureWay,cn=Schemas,cn=Configuration objectclass: top objectclass: ibm-slapdRdbmBackend cn: Directory ibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_init ibm-slapdSuffix: cn=changelog ibm-slapdDbName: ldapclog ibm-slapdDbUserPW: xxx ibm-slapdDbUserID: db2user ibm-slapdChangeLogMaxEntries 5000
In this instance the maximum number of entries the change log can hold is 5000. The default is to have no limitation.
In this release of the IBM Directory an object class ("changeLogEntry") is used to represent changes applied to an IBM Directory server. It also suggests a common location for a container that can hold these objects. The client might update its local copy of directory information by reading the entries within the container and then applying any changes to its local database.
The location of the container that holds "changeLogEntry" objects is obtained by reading the "changeLog" attribute of the root DSE of a server. For example, if the root of the container is "cn=changelog", then the root DSE must have an attribute named "changeLog" with the value "cn=changelog".
Example 1: This example using the ldapsearch command retrieves all change log entries that are recording add operations:
ldapsearch -b "cn=changelog" "(changetype=add)" changenumber=10,cn=changelog objectclass=top objectclass=changelogentry changenumber=10 targetdn=cn=David Campbell, ou=Widget Division, ou=Austin, o=IBM_US, c=US changetime=19990412160345 changetype=add changes=objectclass: organizationalPerson telephonenumber: 1-812-855-7509 internationalisdnnumber: 755-7509 title: Mfg. Assembly seealso: cn=Mary Burnnet, ou=Widget Division, ou=Austin, o=IBM_US, c=US postalcode: 1514 cn: David Campbell
Example 2: This search example retrieves all delete changes where the changenumber attribute is greater than or equal to 5:
ldapsearch -b "cn=changelog" "(& (changetype=delete)(changenumber>=5))" changenumber=9,cn=changelog objectclass=top objectclass=changelogentry changenumber=9 targetdn=cn=david campbell,ou=widget division,ou=austin,o=ibm_us,c=us changetime=19990412160331 changetype=delete
Example 3: This search example retrieves all modify operations, where the changetime attribute is greater than 199904141915000:
ldapsearch -b "cn=changelog" "(&(changetype=modify)(changetime>=199904141915000))" changenumber=32,cn=changelog objectclass=top objectclass=changelogentry changenumber=32 targetdn=cn=bowling team,ou=groups,o=ibm_us,c=us changetime=19990414191505 changetype=modify changes=NOT ASCII changenumber=33,cn=changelog objectclass=top objectclass=changelogentry changenumber=33 targetdn=cn=bowling team,ou=groups,o=ibm_us,c=us changetime=19990414191741 changetype=modify changes=NOT ASCII changenumber=34,cn=changelog objectclass=top objectclass=changelogentry changenumber=34 targetdn=cn=bowling team,ou=groups,o=ibm_us,c=us changetime=19990414191842 changetype=modify changes=NOT ASCII
Example 1: A changeLogEntry representing the addition of a new entry to the directory:
dn: changenumber=1923, cn=changelog
changenumber: 1923
targetdn: cn=Barbara Johnson, ou=Accounting, o=Ace Industry, c=US
changetype: add
changes: cn: Barbara Johnson\ncn: Babs Johnson\nsn: Johnson\n
givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: babs@ace.com\n
objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n
objectclass: inetOrgPerson
Example 2: A changeLogEntry representing the deletion of an entry from the directory:
dn: changenumber=2933, cn=changelog changenumber: 2933 targetdn: cn=Gern Johnson, ou=Product Testing, o=Ace Industry, c=US changetype: delete
Example 3: A changeLogEntry representing the modification of an entry in the directory:
dn: changenumber=5883, cn=changelog
changenumber: 5883
targetdn: cn=Bjorn Johnson, ou=Product Development, o=Ace Industry, c=US
changetype: modify
changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n
add: telephonenumber\ntelephonenumber: +1 212 555 1212\n-
Example 4: A changeLogEntry representing a modrdn operation performed on an entry in the directory:
dn: changenumber=10042, cn=changelog changenumber: 10042 targetdn: cn=Bjorn Johnson, ou=Product Development, o=Ace Industry, c=US changetype: modrdn newrdn: cn=Bjorn J Johnson deleteoldrdn: FALSE
Using the change log facility affects the administration utilities in the following way:
To dump the contents of the change log to a file named ldif.cl:
db2ldif -o ldif.cl -s "cn=changelog"
To pre-load the change log with the contents of an ldif file named ldif.cl:
ldif2db -i ldif.cl
To unconfigure the changelog you can use the ldapucfg command with the -g option or you can either remove or comment out the changelog stanzas.
#dn: cn=Change Log,cn=RDBM Backends,cn=IBM #SecureWay,cn=Schemas,cn=Configuration #objectclass: top #objectclass: ibm-slapdRdbmBackend #cn: Directory #ibm-slapdPlugin: database /bin/libback-rdbm.dll rdbm_backend_init #ibm-slapdSuffix: cn=changelog #ibm-slapdDbName: cldb2 #ibm-slapdDbUserPW: xxx #ibm-slapdDbUserID: db2user
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.
To enable audit logging:
To disable audit logging:
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:
Operation-specific data follows the header and displays operation-specific data, for example,
name: Y249bWFuYWdlcg0K authenticationChoice: simple
entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us attributes: objectclass, cn, sn, telphonenumber
entry: cn=Jim Brown, ou=sales,o=ibm_us,c=us
object: cn=Jim Brown, ou=sales,o=ibm_us,c=us add: mail delete: telephonenumber
Use the following procedures to view the audit log:
To view the error log issue the following command:
more /var/ldap/audit
where /var/ldap/audit is your error log.
To enable error logging:
Mar 29 11:03:23 2001 IBM Directory, Version 4.1 slapd started.
Mar 29 11:07:51 2000 Configuration read securePort 636.
Mar 29 11:07:51 2000 Plugin of type PREOPERATION is successfully
loaded from libDSP.dll.
Mar 29 11:07:51 2000 Plugin of type DATABASE is successfully loaded from
C:\Program Files\IBM\LDAP/bin/libback-rdbm.dll.
Mar 29 11:08:11 2000 Non-SSL port initialized to 389.
Mar 29 11:08:12 2001 IBM Directory, Version 4.1
slapd started.
Mar 29 11:04:05 2000 Configuration read securePort 636.
Mar 29 11:04:05 2000 Configuration read cipher specifications
mask to be 12288.
Mar 29 11:04:05 2000 Plugin of type PREOPERATION is successfully
loaded from libDSP.dll.
Mar 29 11:04:05 2000 Plugin of type DATABASE is successfully loaded from
C:\Program Files\IBM\LDAP/bin/libback-rdbm.dll
Mar 29 11:04:24 2000 Configuration file successfully read.
Mar 29 11:04:24 2000 Non-SSL port initialized to 389.
Mar 29 11:04:25 2001 IBM Directory, Version 4.1
slapd started.
Use the following procedures to view the error log.
To view the error log issue the following command:
more /tmp/slapd.errors
where tmp/slapd.errors is your error log.
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.
To enable event notification:
To disable event notification:
See the IBM Directory Server Version 4.1 C-Client SDK Programming Reference for more information about event notification.
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 operations is dependent on another operations because if one of the operations fails, the entire transaction fails. Transaction settings determine the limits on the transaction activity allowed on the server.
To enable transaction processing:
To disable transaction processing:
See the IBM Directory Server Version 4.1 C-Client SDK Programming Reference for more information about transaction support.
This section describes the utilities that can be run from a command prompt.
The ldapdelete, ldapmodify, ldapadd, ldapmodrdn, and ldapsearch utilities all use the ldap_bind API. When bind is invoked, several results can be returned. Following are bind results using various combinations of user IDs and passwords.
This section provides a description of the client utilities. They are also documented in "Chapter 2. Ldap Utilities" in the IBM Directory Server Version 4.1: Client SDK Programming Reference.
LDAP modify-entry and LDAP add-entry tools
ldapmodify [-a] [-b] [-c] [-C charset] [-d debuglevel][-D binddn][-f file] [-h ldaphost] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename] [-O hopcount] [-p ldapport] [-P keyfilepw] [-r] [-R] [-v] [-V] [-w passwd | ?] [-Z] ldapadd [-b] [-c] [-d debuglevel][-D binddn][-f file] [-h ldaphost] [-K keyfile] [-M] [-n] [-N certificatename] [-p ldapport] [-P keyfilepw] [-r] [-R] [-v] [-V] [-w passwd | ?] [-Z]
ldapmodify is a command-line interface to the ldap_modify and ldap_add library calls. ldapadd is implemented as a renamed version of ldapmodify. When invoked as ldapadd, the -a (add new entry) flag is turned on automatically.
ldapmodify opens a connection to an LDAP server, and binds to the server. You can use ldapmodify to modify or add entries. The entry information is read from standard input or from file through the use of the -f option.
To display syntax help for ldapmodify or ldapadd, type
ldapmodify -?
or
ldapadd -?
A default keyring file that is, ldapkey.kdb, and the associated password stash file that is, ldapkey.sth, are installed in the /lib directory under LDAPHOME, where LDAPHOME is the path to the installed LDAP support. LDAPHOME varies by operating system platform:
See the IBM Directory C-Client SDK Programming Reference for more information about default key database files, and default Certificate Authorities.
If a keyring database file cannot be located, a "hard-coded" set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of certificate authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. For more information on managing an SSL key database, see Appendix B, Using gsk5ikm. Also see the SSL Notes and Secure Sockets Layer for more information about SSL and certificates.
This parameter effectively enables the -Z switch.
The contents of file (or standard input if no -f flag is given on the command line) should conform to the ldif format.
An alternative input format is supported for compatibility with older versions of ldapmodify. This format consists of one or more entries separated by blank lines, where each entry looks like the following:
Distinguished Name (DN) attr=value [attr=value ...]
where attr is the name of the attribute and value is the value.
By default, values are added. If the -r command line flag is given, the default is to replace existing values with the new one. It is permissible for a given attribute to appear more than once, for example, to add more than one value for an attribute. Also note that you can use a trailing `\\' to continue values across lines and preserve new lines in the value itself. This is useful for modifying QUIPU iattr attributes among others.
attr should be preceded by a - to remove a value. The = and value should be omitted to remove an entire attribute.
attr should be preceded by a + to add a value in the presence of the -r flag.
Assuming that the file /tmp/entrymods exists and has the following contents:
dn: cn=Modify Me, o=University of Higher Learning, c=US
changetype: modify
replace: mail
mail: modme@student.of.life.edu
-
add: title
title: Grand Poobah
-
add: jpegPhoto
jpegPhoto: /tmp/modme.jpeg
-
delete: description
-
the command:
ldapmodify -b -r -f /tmp/entrymods
will replace the contents of the Modify Me entry's mail attribute with the value modme@student.of.life.edu, add a title of Grand Poobah, and the contents of the file /tmp/modme.jpeg as a jpegPhoto, and completely remove the description attribute. These same modifications can be performed using the older ldapmodify inout format:
cn=Modify Me, o=University of Higher Learning, c=US
mail=modme@student.of.life.edu
+title=Grand Poobah
+jpegPhoto=/tmp/modme.jpeg
-description
and the command:
ldapmodify -b -r -f /tmp/entrymods
Assuming that the file /tmp/newentry exists and has the following contents:
dn: cn=John Doe, o=University of Higher Learning, c=US
objectClass: person
cn: John Doe
cn: Johnny
sn: Doe
title: the world's most famous mythical person
mail: johndoe@student.of.life.edu
uid: jdoe
the command:
ldapadd -f /tmp/entrymods
adds a new entry for John Doe, using the values from the file /tmp/newentry.
Assuming that the file /tmp/newentry exists and has the contents:
dn: cn=John Doe, o=University of Higher Learning, c=US
changetype: delete
the command:
ldapmodify -f /tmp/entrymods
removes John Doe's entry.
If entry information is not supplied from file through the use of the -f option, the ldapmodify command will wait to read entries from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
To use the SSL-related functions associated with this utility, the SSL libraries and tools must be installed. The SSL libraries and tools are provided with IBM's Global Security Kit (GSKit), which includes security software developed by RSA Security Inc.
The content of a client's key database file is managed with the gsk5ikm utility. For more information on this Java utility, see Appendix B, Using gsk5ikm. The gsk5ikm utility is used to define the set of trusted certification authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as 'trusted', you can establish a trust relationship with LDAP servers that use 'trusted' certificates issued by one of the trusted CAs. The gsk5ikm utility can also be used to obtain a client certificate, so that client and server authentication can be performed.
If the LDAP servers accessed by the client use server authentication only, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s. For example, if the LDAP server is using a high-assurance VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed server certificate, the administrator of the LDAP server can supply you with a copy of the server's certificate request file. Import the certificate request file into your key database file and mark it as trusted.
If the LDAP servers accessed by the client use client and server authentication, it is necessary to:
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
ldapdelete, ldapmodrdn, ldapsearch
LDAP delete-entry tool
ldapdelete [-b searchbase] [-c] [-C charset] [-d debuglevel][-D binddn][-f file]
[-h ldaphost] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename]
[-O hopcount] [-p ldapport] [-P keyfilepw] [-R] [-v] [-V]
[-w passwd | ?] [-Z] [dn]...
ldapdelete is a command-line interface to the ldap_delete library call.
ldapdelete opens a connection to an LDAP server, binds, and deletes one or more entries. If one or more Distinguished Name (DN) arguments are provided, entries with those DNs are deleted. Each DN is a string-represented DN. If no DN arguments are provided, a list of DNs is read from standard input, or from file if the -f flag is used.
To display syntax help for ldapdelete, type:
ldapdelete -?
.
A default keyring file that is, ldapkey.kdb, and the associated password stash file that is, ldapkey.sth, are installed in the /lib directory under LDAPHOME, where LDAPHOME is the path to the installed LDAP support. LDAPHOME varies by operating system platform:
See IBM Directory C-Client SDK Programming Reference for more information about default key database files, and default Certificate Authorities.
If a keyring database file cannot be located, a "hard-coded" set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of certificate authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. For more information on managing an SSL key database, see Appendix B, Using gsk5ikm. Also see the SSL Notes and Secure Sockets Layer for more information about SSL and certificates.
This parameter effectively enables the -Z switch.
The following command,
ldapdelete "cn=Delete Me, o=University of Life, c=US"
attempts to delete the entry named with commonName "Delete Me" directly below the University of Life organizational entry. It might be necessary to supply a binddn and passwd for deletion to be allowed (see the -D and -w options).
If no DN arguments are provided, the ldapdelete command waits to read a list of DNs from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
To use the SSL-related functions associated with this utility, the SSL libraries and tools must be installed. The SSL libraries and tools are provided with IBM's Global Security Kit (GSKit), which includes security software developed by RSA Security Inc.
The content of a client's key database file is managed with the gsk5ikm utility. For more information on this Java utility, see Appendix B, Using gsk5ikm. The gsk5ikm utility is used to define the set of trusted certification authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as 'trusted', you can establish a trust relationship with LDAP servers that use 'trusted' certificates issued by one of the trusted CAs. The gsk5ikm utility can also be used to obtain a client certificate, so that client and server authentication can be performed.
If the LDAP servers accessed by the client use server authentication only, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s. For example, if the LDAP server is using a high-assurance VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed server certificate, the administrator of the LDAP server can supply you with a copy of the server's certificate request file. Import the certificate request file into your key database file and mark it as trusted.
If the LDAP servers accessed by the client use client and server authentication, it is necessary to:
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
ldapadd ,ldapmodify, ldapmodrdn, ldapsearch,
LDAP modify-entry RDN tool
ldapmodrdn [-c] [-C charset] [-d debuglevel][-D binddn] [-f file] [-h ldaphost] [-K keyfile] [-m mechanism] [-M] [-n] [-N certificatename] [-O hopcount] [-p ldapport] [-P keyfilepw] [-r] [-R] [-v] [-V] [-w passwd | ?] [-Z] [dnrdn]
ldapmodrdn is a command-line interface to the ldap_modrdn library call.
ldapmodrdn opens a connection to an LDAP server, binds, and modifies the RDN of entries. The entry information is read from standard input, from file through the use of the - f option, or from the command-line pair dn and rdn.
See LDAP Distinguished Names for information about RDNs (Relative Distinguished Names) and DNs (Distinguished Names).
To display syntax help for ldapmodrdn, type:
ldapmodrdn -?
A default keyring file (that is, ldapkey.kdb) and the associated password stash file (that is, ldapkey.sth) are installed in the /lib directory under LDAPHOME, where LDAPHOME is the path to the installed LDAP support. LDAPHOME varies by operating system platform:
See IBM Directory C-Client SDK Programming Reference for more information about default key database files, and default Certificate Authorities.
If a keyring database file cannot be located, a "hard-coded" set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of certificate authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. For more information on managing an SSL key database, see Appendix B, Using gsk5ikm. Also see the SSL Notes and Secure Sockets Layer for more information about SSL and certificates.
This parameter effectively enables the -Z switch.
If the command-line arguments dn and rdn are given, rdn replaces the RDN of the entry specified by the DN, dn. Otherwise, the contents of file (or standard input if no - f flag is given) consist of one or more entries:
Distinguished Name (DN) Relative Distinguished Name (RDN)
One or more blank lines may be used to separate each DN and RDN pair.
Assuming that the file /tmp/entrymods exists and has the contents:
cn=Modify Me, o=University of Life, c=US cn=The New Me
the command:
ldapmodrdn -r -f /tmp/entrymods
changes the RDN of the Modify Me entry from Modify Me to The New Me and the old cn, Modify Me is removed.
If entry information is not supplied from file through the use of the -f option (or from the command-line pair dn and rdn), the ldapmodrdn command waits to read entries from standard input. To break out of the wait, use Ctrl+C or Ctrl+D.
To use the SSL-related functions associated with this utility, the SSL libraries and tools must be installed. The SSL libraries and tools are provided with IBM's Global Security Kit (GSKit), which includes security software developed by RSA Security Inc.
The content of a client's key database file is managed with the gsk5ikm utility. For more information on this Java utility, see Appendix B, Using gsk5ikm. The gsk5ikm utility is used to define the set of trusted certification authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as 'trusted', you can establish a trust relationship with LDAP servers that use certificates issued by one of the trusted CAs. The gsk5ikm utility can also be used to obtain a client certificate, so that client and server authentication can be performed.
If the LDAP servers accessed by the client use server authentication only, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted, including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s. For example, if the LDAP server is using a high-assurance VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed server certificate, the administrator of the LDAP server can supply you with a copy of the server's certificate request file. Import the certificate request file into your key database file and mark it as trusted.
If the LDAP servers accessed by the client use client and server authentication, it is necessary to:
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
ldapadd, ldapdelete, ldapmodify, ldapsearch
LDAP search tool and sample program
ldapsearch [-a deref] [-A] [-b searchbase] [-B] [-C charset] [-d debuglevel] [-D binddn][-f file] [-F sep] [-h ldaphost] [-K keyfile] [-l timelimit] [-L] [-m mechanism] [-M] [-n] [-N certificatename][-O hopcount] [-p ldapport] [-P keyfilepw] [-q pagesize] [-R] [-s scope ] [-t] [-T seconds][-v] [-V] [-w passwd | ?] [-z sizelimit] [-Z] filter [attrs...] [-o attributename]
ldapsearch is a command-line interface to the ldap_search library call.
ldapsearch opens a connection to an LDAP server, binds, and performs a search using the filter. The filter should conform to the string representation for LDAP filters (see ldap_search in the IBM Directory Server Version 4.1 C-Client SDK Programming Reference for more information on filters).
If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attrs are listed, all attributes are returned.
To display syntax help for ldapsearch, type ldapsearch -?.
A default keyring file (that is, ldapkey.kdb) and the associated password stash file (that is, ldapkey.sth) are installed in the /lib directory under LDAPHOME, where LDAPHOME is the path to the installed LDAP support. LDAPHOME varies by operating system platform:
See the "Default Keyring and Password" section of the LDAP_SSL API in the IBM C-Client SDK Programming Reference for more information about default key database files, and default Certificate Authorities.
If a keyring database file cannot be located, a "hard-coded" set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of certificate authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. For more information on managing an SSL key database, see Appendix B, Using gsk5ikm. Also see the SSL Notes below and LDAP SSL APIs for more information about SSL and certificates.
This parameter effectively enables the -Z switch.
-o sn -o -givenname
Thus, the syntax of the sort parameter is as follows:
[-]<attribute name>[:<matching rule OID>]
where
The default ldapsearch operation is not to sort the returned results.
-q 25 -T 15
If the -v (verbose) parameter is specified, ldapsearch lists how many entries have been returned so far, after each page of entries returned from the server, for example, 30 total entries have been returned.
Multiple -q parameters are enabled such that you can specify different page sizes throughout the life of a single search operation. In the following example, the first page is 15 entries, the second page is 20 entries, and the third parameter ends the paged result/search operation:
-q 15 -q 20 -q 0
In the following example, the first page is 15 entries, and all the rest of the pages are 20 entries, continuing with the last specified -q value until the search operation completes:
-q 15 -q 20
The default ldapsearch operation is to return all entries in a single request. No paging is done for the default ldapsearch operation.
<filter> ::='('<filtercomp>')'
<filtercomp> ::= <and>|<or>|<not>|<simple>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter>|<filter><filtertype>
<simple> ::= <attributetype><filtertype>
<attributevalue>
<filtertype> ::= '='|'~='|'<='|'>='
The '~=' construct is used to specify approximate matching. The representation for <attributetype> and <attributevalue> are as described in "RFC 2252, LDAP V3 Attribute Syntax Definitions". In addition, <attributevalue> can be a single * to achieve an attribute existence test, or can contain text and asterisks ( * ) interspersed to achieve substring matching.
For example, the filter "mail=*" finds any entries that have a mail attribute. The filter "mail=*@student.of.life.edu" finds any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash (\) character.
See "RFC 2254, A String Representation of LDAP Search Filters" for a more complete description of allowable filters.
If one or more entries are found, each entry is written to standard output in the form:
Distinguished Name (DN)
attributename=value
attributename=value
attributename=value
...
Multiple entries are separated with a single blank line. If the -F option is used to specify a separator character, it will be used instead of the `=' character. If the -t option is used, the name of a temporary file is used in place of the actual value. If the -A option is given, only the "attributename" part is written.
The following command:
ldapsearch "cn=john doe" cn telephoneNumber
performs a subtree search (using the default search base) for entries with a commonName of "john doe". The commonName and telephoneNumber values is retrieved and printed to standard output. The output might look something like this if two entries are found:
cn=John E Doe, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Higher Learning, c=US cn=John Doe cn=John Edward Doe cn=John E Doe 1 cn=John E Doe telephoneNumber=+1 313 555-5432 cn=John B Doe, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US cn=John Doe cn=John B Doe 1 cn=John B Doe telephoneNumber=+1 313 555-1111
The command:
ldapsearch -t "uid=jed" jpegPhoto audio
performs a subtree search using the default search base for entries with user id of "jed". The jpegPhoto and audio values are retrieved and written to temporary files. The output might look like this if one entry with one value for each of the requested attributes is found:
cn=John E Doe, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US audio=/tmp/ldapsearch-audio-a19924 jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924
This command:
ldapsearch -L -s one -b "c=US" "o=university*" o description
will perform a one-level search at the c=US level for all organizations whose organizationName begins with university. Search results will be displayed in the LDIF format (see LDAP Data Interchange Format). The organizationName and description attribute values will be retrieved and printed to standard output, resulting in output similar to this:
dn: o=University of Alaska Fairbanks, c=US o: University of Alaska Fairbanks description: Preparing Alaska for a brave new tomorrow description: leaf node only dn: o=University of Colorado at Boulder, c=US o: University of Colorado at Boulder description: No personnel information description: Institution of education and research dn: o=University of Colorado at Denver, c=US o: University of Colorado at Denver o: UCD o: CU/Denver o: CU-Denver description: Institute for Higher Learning and Research dn: o=University of Florida, c=US o: University of Florida o: UFl description: Shaper of young minds ...
To use the SSL-related functions associated with this utility, the SSL libraries and tools must be installed. The SSL libraries and tools are provided with IBM's Global Security Kit (GSKit), which includes security software developed by RSA Security Inc.
The contents of a client's key database file is managed with the gsk5ikm utility. For more information on this Java utility, see Appendix B, Using gsk5ikm. The gsk5ikm utility is used to define the set of trusted certification authorities (CAs) that are to be trusted by the client. By obtaining certificates from trusted CAs, storing them in the key database file, and marking them as trusted, you can establish a trust relationship with LDAP servers that use certificates issued by one of the CAs that are marked as trusted. The gsk5ikm utility can also be used to obtain a client certificate, so that client and server authentication can be performed.
If the LDAP servers accessed by the client use server authentication only, it is sufficient to define one or more trusted root certificates in the key database file. With server authentication, the client can be assured that the target LDAP server has been issued a certificate by one of the trusted CAs. In addition, all LDAP transactions that flow over the SSL connection with the server are encrypted (including the LDAP credentials that are supplied on the ldap_bind or ldap_simple_bind_s (see the LDAP_Bind APIs).
For example, if the LDAP server is using a high-assurance VeriSign certificate, you should obtain a CA certificate from VeriSign, import it into your key database file, and mark it as trusted. If the LDAP server is using a self-signed server certificate, the administrator of the LDAP server can supply you with a copy of the server's certificate request file. Import the certificate request file into your key database file and mark it as trusted.
If the LDAP servers accessed by the client use client and server authentication, it is necessary to:
Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.
ldapadd, ldapdelete, ldapmodify, ldapmodrdn
This sections describes the server utilities.
Notes:
The LDAP Data Interchange Format (LDIF) tool ldif is a shell-accessible utility that converts arbitrary data values to LDIF. It reads input values from standard input and produces LDIF.
LDIF is used to represent LDAP entries in text form. The purpose of this information is to describe the LDAP Data Interchange Format (LDIF), as used by the ldapmodify, ldapadd, and ldapsearch command-line utilities.
The basic form of an LDIF entry is:
dn: <distinguished name>: <attrtype>: <attrvalue> <attrtype>: <attrvalue> ...
A line can be continued by starting the next line with a single space or tab character, for example:
dn: cn=Barbara J Jensen, o=University of Michi
gan, c=US
Multiple attribute values are specified on separate lines, for example:
cn: Barbara J Jensen cn: Babs Jensen
If an <attrvalue> contains a non-printing character, or begins with a space or a colon ":", the <attrtype> is followed by a double colon and the value is encoded in base 64 notation. The value that begins with a space would be encoded like this:
cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
Multiple entries within the same LDIF file are separated by blank lines.
Adding the first replica object would look something like the following in LDIF format:
dn: cn=myReplica, cn=localhost cn: myReplica objectclass : replicaObject replicaHost: mymachine.austin.ibm.com replicaBindDn: cn=Admin, c=US replicaCredentials: password replicaPort: 1010
The replicaBindDn (cn=Admin, c=US) must be the same as the master server DN on the replica (mymachine.austin.ibm.com). Similarly, replicaCredentials must be the same as the masterServerPassword on the replica, and the replicaPort must be the same as the port on the replica.
dn: cn=John Doe, ou=Austin, o=IBM, c=US
objectclass: top
objectclass: person
objectclass: organizationalPerson
cn: John Doe
sn: Doe
dept: abcd
aclEntry: access-id:cn=Bert Hello, ou=Austin, o=IBM, c=US:object:da:normal
:rwsc:sensitive:rsc
aclEntry: group:cn=Anybody::normal:rsc
aclEntry: access-id:cn=Amy Too, ou=Austin, o=IBM, c=US:object:da:normal
:rwsc:sensitive:rsc:critical:rsc
aclPropagate:TRUE
entryOwner: group:cn=personnel, ou=Austin, o=IBM, c=US
ownerPropagate: TRUE
This program is used to load entries specified in text LDAP Directory Interchange Format (LDIF) into a directory stored in a relational database. The database must already exist. ldif2db can be used to add entries to an empty directory database or to a database that already contains entries.
Notes:
All other command line inputs result in a syntax error message, after which the correct syntax is displayed.
The bulkload utility is used to load the directory data from an ldif file. It is a faster alternative to ldif2db and is available for bulk-loading large amounts of data in LDIF format.
Notes:
update database configuration for ldapdb2 using LOGRETAIN OFF USEREXIT OFF
bulkload -i <ldiffile> -s $
Schema checking verifies that all object classes and attributes have been defined, that all attributes specified for each entry comply with the list of "required" and "allowed" attributes in the object class definition, and that binary attribute values are in the correct 64-bit encoded form.
The recommended approach is to use the -S only option first to validate the data, and thereafter to use the default -S no whenever loading the data into the directory.
For better performance the bulkload tool assumes that the data in the input file is correct or that the data has been checked in an earlier loading. The bulkload tool can, however, perform some basic checks on the input data.
The bulkload utility cannot run while the directory server (slapd) is running.
In addition to the disk space required for data storage in the local database directory, the bulkload tool requires temporary storage for data manipulation before inserting the data into the database. The default path for this temporary storage is platform specific. See the -L option description for the path names. You can change the path using the -L option:
bulkload -i <ldiffile> -L /newpath
You must have write permission to this directory. You need temporary storage at least 2.5 times the size of the ldif file that is available in the ldapimport directory. You still might need additional temporary storage depending on your data.
If you receive an error like the following:
SQL3508N Error in accessing a file of type "SORTDIRECTORY" during load or load query. Reason code: "2". Path: "/u/ldapdb2/sqllib/tmp/".
you need to set the environment variable DB2SORTTMP to a directory (or directories) in a file system with more space to be utilized during the bulkload. Multiple directories can be specified separated by a comma ( , ) as in:
export DB2SORTTMP=/sortdir1,/sortdir2
When running bulkload, inspect the output messages carefully. If errors occur during execution, the directory might be incompletely populated. You might need to drop all the LDAP tables, or drop the database (re-create an empty database), and start over. If this happens, no data was added to the directory, and the bulkload must be attempted again. In addition, you might lose data when you drop all the LDAP tables.
The file /usr/ldap/examples/sample.ldif includes sample data. You can use the data in the file to experiment with populating a directory using the bulkload tool, or you can use the ldif2db command line utility. However, the ldif2db utility might be considerably slower than the bulkload utility for large amounts of data.
For performance reasons, the bulkload tool does not check for duplicate entries. Ensure that your input ldif file does not contain duplicate entries. If any duplicates exist, remove the duplicate entries.
If bulkload fails at the DB2 LOAD phase, see the db2load.log file for the reasons. This log file is located on the Windows operating systems in c:\tmp\ldapimport, on AIX operating systems in /tmp/ldapimport, and on Linux , Solaris, and HP operating systems in /var/ldap/ldapimport. If the -L option was specified, find the file in the directory defined by the -L option. Correct the problem and rerun bulkload. Bulkload reloads the files from the last successful load consistency point.
When bulkload fails, the recovery information is stored in <installation directory>/etc/bulkload_status. This file is not removed until all of the data is loaded successfully. This insures the data integrity of the directory. If you decide to reconfigure the database and start over, the bulkload_status file needs to be removed manually or bulkload still tries to recover from the last successful load point.
This program is used to dump entries from a directory stored in a relational database into a text file in LDAP Directory Interchange Format (LDIF).
All other command line inputs result in a syntax error message, after which the proper syntax is displayed.
The IBM Directory (Version 4.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.
The IBM Directory supports standard directory schema as defined in the following:
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:
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 is used only in the subschema entry as follows:
( <objectClass-oid-TBD> NAME 'IBMsubschema' AUXILIARY
MAY IBMattributeTypes )
The IBMAttributeTypes object class 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
( attr-oid ... SYNTAX syntax-oid{len} ... )
can be used to indicate that the attributetype with oid attr-oid has a maximum length.
Schema configuration provides values for the following attribute types:
The syntax of these schema definitions is based on the LDAP Version 3 RFCs.
A sample configuration file could contain:
objectclasses=( 1.3.6.1.4.1.1466.101.120.111
NAME 'extensibleObject'
SUP top AUXILIARY )
objectclasses=( 2.5.20.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 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 4.1: Client SDK Programming Reference for more information about the ldap_search API.
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 the IBM Directory Version 4.1: Client SDK Programming Reference for more information about the ldap_modify API.
Not all schema changes are allowed. Change restrictions include the following:
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.
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 with a proper 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:
The following items are checked for object classes:
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 slapd32.conf configuration directive. See the IBM Directory Server Version 4.1 Installation and Configuration Guide for Multiplatforms for information about schema configuration attributes.
To comply with the schema an entry is checked for the following conditions:
Dynamic schema changes can be performed only by a master server or a peer server (for replication) and administrator DN.
When a dynamic schema change is performed, it is replicated just like any other ldap_modify operation.
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 4.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.
IBM Directory 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 a suffix. 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 contains the following information:
1.3.18.0.2.8.1 DESC 'IBM Attribute Type Description' )
1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN - distinguished name' )
1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String -
case-insensitive string' )
1.3.6.1.4.1.1466.115.121.1.16 DESC 'DIT Content Rule Description' )
1.3.6.1.4.1.1466.115.121.1.17 DESC 'DIT Structure Rule Description' )
1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' )
1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String - case-sensitive
string' )
1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER - integral number' )
1.3.6.1.4.1.1466.115.121.1.3 DESC 'Attribute Type Description' )
1.3.6.1.4.1.1466.115.121.1.30 DESC 'Matching Rule Description' )
1.3.6.1.4.1.1466.115.121.1.31 DESC 'Matching Rule Use Description' )
1.3.6.1.4.1.1466.115.121.1.35 DESC 'Name Form Description' )
1.3.6.1.4.1.1466.115.121.1.37 DESC 'Object Class Description' )
1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' )
1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary - octet string' )
1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' )
1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' )
1.3.6.1.4.1.1466.115.121.1.54 DESC 'LDAP Syntax Description' )
1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean - TRUE/FALSE' )
MatchingRules= ( 2.5.13.5 NAME 'caseExactMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.1.26 ) MatchingRules= ( 2.5.13.2 NAME 'caseIgnoreMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) MatchingRules= ( 2.5.13.7 NAME 'caseExactSubstringsMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) MatchingRules= ( 2.5.13.6 NAME 'caseExactOrderingMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) MatchingRules= ( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) MatchingRules= ( 2.5.13.3 NAME 'caseIgnoreOrderingMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) MatchingRules= ( 1.3.18.0.2.4.405 NAME 'distinguishedNameOrderingMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) MatchingRules= ( 2.5.13.1 NAME 'distinguishedNameMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) MatchingRules= ( 2.5.13.28 NAME 'generalizedTimeOrderingMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) MatchingRules= ( 2.5.13.27 NAME 'generalizedTimeMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) MatchingRules= ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) MatchingRules= ( 1.3.6.1.4.1.1466.109.114.1 NAME 'caseExactIA5Match' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) MatchingRules= ( 2.5.13.29 NAME 'integerFirstComponentMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) MatchingRules= ( 2.5.13.14 NAME 'integerMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) MatchingRules= ( 2.5.13.17 NAME 'octetStringMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) MatchingRules= ( 2.5.13.0 NAME 'objectIdentifierMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) MatchingRules= ( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) MatchingRules= ( 2.5.13.21 NAME 'telephoneNumberSubstringsMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) MatchingRules= ( 2.5.13.20 NAME 'telephoneNumberMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) MatchingRules= ( 2.5.13.25 NAME 'uTCTimeMatch' \ SYNTAX 1.3.6.1.4.1.1466.115.121.1.53 )
The schema information can be modified through the ldap_modify API. 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. Add or replace a schema entry with the LDAP Version 3 definition or with the IBM attribute extension definition or with both definitions.
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.
Schema update operations are checked against the schema class hierarchy for consistency before being processed and committed.
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:
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:
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
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
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.
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:
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:
For server authentication, you can manually edit the slapd32.conf file under the cn=SSL, cn=Configuration entry. You can either omit sslAuth attribute or set it as follows:
ibm-slapdSSLAuth: serverauth
To configure SSL for the IBM Directory use the Server Administration, which lists the following configuration settings:
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 certificate authority (CA), and prepare them for use by the IBM Directory are outlined in the following:
When you receive the resulting certificate from the certificate authority (CA):
If you are using the IBM Directory in an intranet environment, use gsk5ikm to create your own server certificates. You can also use gsk5ikm 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.
See Appendix B, Using gsk5ikm for additional information.
Notes:
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 (VeriSign, for example, or the creator of a self-signed server certificate), imported into the client's key database file, and 'marked' as trusted.
See Appendix B, Using gsk5ikm for additional information.
When the LDAP client creates a secure SSL connection with the server, it now 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.
The following is a list of the ciphers supported:
These ciphers are stored in the configuration file using the sslCipherSpecs keyword as the decimal representation of the sum of the values defined above. For example, to use only Triple DES, the value is 256. In this case, only clients that also support Triple DES would be able to establish an SSL connection with the server.
To migrate the old key ring file which was created from MKKF utility, do the following steps:
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:
When using SSL to secure LDAP communication with the IBM Directory server with client authentication mechanism, you can manually edit the slapd32.conf file under the cn=SSL, cn=Configuration entry to add the new line:
ibm-slapdSSLAuth: serverclientauth
The IBM Directory supports Kerberos Version 1.2 servers, such as the IBM Network Authentication Service, on AIX servers and clients, and Windows NT and Windows 2000 clients only.
If you have not done so already, click the arrow to the left of Security in the navigation area, then click Kerberos.
To enable Kerberos authentication:
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 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.
The IBM Directory Management Tool provides a graphical user interface that enables you to manage information stored in directory servers. Use the tool to:
The Directory Management Tool is an optionally installable part of the client package of the IBM Directory Server Version 4.1 product.
To start the tool, type dmt in a command window. The dmt command has an optional parameter:
dmt -f c:\temp\dmtservers.conf
To configure the Directory Management Tool, edit the configuration file located at <installation directory>/etc/dmt.conf. For example, if you edit the file to contains these lines:
server1.url=ldap://ldapsrv.austin.ibm.com:389 server1.security.bindDN=cn=admin server1.security.password=secret server1.security.ssl.keyclass=
When started, the tool connects to the non-SSL port 389 of a directory server at machine ldapsrv.austin.ibm.com. It logs in to the server as DN: cn=admin using password secret.
Multiple servers can be specified in the configuration file. For example:
server2.url=ldaps://localhost.austin.ibm.com:636 server2.security.bindDN=cn=admin server2.security.password=secret server2.security.ssl.keyclass=localhost
If you do not want to keep a clear password in the configuration file in an unprotected directory, leave the principal name empty to perform an initial bind to the server as an anonymous user, then rebind with the correct DN. If the tool is started without default servers and login users defined in the configuration file, use the Add server button to add servers. If Secure Socket Layer (SSL) is used, specify the proper keyclass file. The keyclass file contains certificate information.
After the tool has been started the, the application window has four parts:
You can use the Directory Management Tool to:
When the Directory Management Tool is started, connections are made to the servers specified in the configuration file. If a directory User DN and password are not provided in the Directory Management Tool configuration file, the connection to the server is anonymous. Anonymous users can browse the directory tree and schema, but in most instances cannot perform directory updates.
Adding a User DN and password to the configuration file enables you to connect to the specified server as the specified user every time you launch the Directory Management Tool. The default configuration file is <ldap>/etc/dmt.conf.
For example, adding:
server1.url=ldap://test.ibm.com:389
server1.security.bindDN=cn=root
server1.security.password=secret
to dmt.conf connects to the server test.ibm.com as user cn=root with the password secret.
To reconnect to an already connected server as a different user,
If you select Authenticated but do not enter a User DN, the connection defaults to Anonymous.
To view the server status, expand the Server category in the navigation area, then click Status.
The status panel displays:
If you have not done so already, expand the Server category in the navigation area, then click Properties.
The current bind DN, subschema entry, supported LDAP protocol versions, and the naming contexts that the server holds are displayed.
The Directory Management Tool displays servers as tabs at the top of the navigation area. Each tab displays the name of the associated directory server and an icon to indicate if the server is a:
Master server
Replica server
Peer server
To add a new server, click Add server at the bottom of the navigation area.
Depending upon whether you are connecting to the server using Secure Sockets Layer (SSL) and the type of authentication you select, you are prompted for additional information.
If you want to connect to the server without using SSL:
If you want to connect to the server using SSL:
To enable SSL on the Directory Management Tool you must perform the following.
Notes:
export LIBPATH=/usr/ldap/java/bin:/usr/ldap/java/bin/classic:$LIBPATH
On the SSL server:
gsk5ikm
Use the default settings for all the other fields.
On the client:
java com.ibm.ikeyman.Ikeyman
Use the default settings for all the other fields.
Use the default settings for all the other fields.
On the SSL Server:
gsk5ikm
See Appendix B, Using gsk5ikm for more information.
The Directory Management Tool displays server as tabs at the top of the navigation area. Each tab displays the name of the associated directory server. To delete a server:
IBM Directory Server Administration is a web-based interface through which you can setup and maintain an LDAP server and its backend database.
If you have not already done so, expand the Server category in the navigation area.
For additional information, see Server Administration graphical user interface.
Three tasks display a toolbar at the top of the work area. The toolbar, be default, displays icons and text. You can modify the toolbar settings to display only icons or only text by editing the configuration file. The default configuration file is dmt.conf.
To edit the configuration file:
The toolbar contains a series of icons depending on the task selected in the navigation area.
The Browse tree toolbar displays:
- Click the Search icon to search the directory tree.
- Click the Expand icon to expand all entries in the selected section
of the directory tree.
- Click the Add icon to add a directory entry beneath the selected
entry.
- Click the Edit icon to edit the selected entry.
- Click the Duplicate icon to add a new entry with the attributes of
the selected entry.
- Click the Delete icon to delete the selected entry.
- Click the ACLs icon to add or edit an Access Control List (ACL) to
the selected directory entry.
- Click the Edit RDN icon to edit the relative distinguished name of
the selected entry.
- Click the Add auxiliary class icon to add an auxiliary class to the
selected entry.
The View object classes toolbar displays:
- Click the Search icon to search for an object class..
- Click the Add icon to add an object class.
- Click the Edit icon to edit the selected object class.
- Click the Delete icon to delete the selected object class.
The View object classes toolbar also contains a Sort by drop-down list. The default sort order for object classes is by object class name. You can also sort by:
The View attributes toolbar displays:
- Click the Search icon to search for an attribute.
- Click the Add icon to add an attribute.
- Click the Edit icon to edit the selected attribute.
- Click the Delete icon to delete the selected attribute.
The View attributes toolbar also contains a Sort by drop-down list. The default sort order for attributes is by attribute name. You can sort by:
See the Directory Management Tool online helps for additional information.
If you have not done so already, expand the Directory tree category in the navigation area, then expand Browse Tree.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 tool bar.
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, acl, 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:
Each of these attributes can be managed using LDIF notation. The following defines the syntax for the ACI and entryOwner attributes using baccus naur form (BNF).
<aclEntry> ::= <subject> [ ":" <rights> ]
<aclPropagate> ::= "true" | "false"
<entryOwner> ::= <subject>
<ownerPropagate> ::= "true" | "false"
<subject> ::= <subjectDnType> ':' <subjectDn> |
<pseudoDn>
<subjectDnType> ::= "role" | "group" | "access-id"
<subjectDn> ::= <DN>
<DN> ::= distinguished name as described in RFC 2251, section 4.1.3.
<pseudoDn> ::= "group:cn=anybody" | "group:cn=authenticated" |
"access-id:cn=this"
<rights> ::= <accessList> [":" <rights> ]
<accessList> ::= <objectAccess> | <attributeAccess> |
<attributeClassAccess>
<objectAccess> ::= "object:" [<action> ":"] <objectPermissions>
<action> ::= "grant" | "deny"
<objectPermisssions> ::= <objectPermission> [ <objectPermissions> ]
<objectPermission> ::= "a" | "d" | ""
<attributeAccess> ::= "at." <attributeName> ":" [<action> ":"]
<attributePermissions>
<attributeName> ::= attributeType name as described in RFC 2251,
section 4.1.4.
(OID 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"
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.
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.
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:
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:
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.
| Operation | Permission Needed |
| ldapadd | add (on parent) |
| ldapdelete | delete (on object) |
| ldapmodify | write (on attributes being modified) |
| ldapsearch |
|
| ldapmodrdn | write (on RDN attributes) |
| ldapcompare | compare (on compared attribute) |
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 and aclSource. These are attributes maintained by the LDAP server and read only to the directory users. OwnerSource and aclSource are described in the Propagation section. The attributes that define the access control, namely aclEntry, aclPropagate, entryOwner and ownerPropagate, are in the restricted class. All users have read access to the restricted attributes but only entryOwners can create, modify, and delete these attributes.
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.
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.
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:
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.
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.
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.
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.
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:
This user gets:
For another example, with the following aclEntries:
The user has:
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 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
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.
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
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
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
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.
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.
The same can be done to delete aclEntry completely:
dn: cn = some entry changetype: modify delete: aclEntry
Deleting the last ACI or entryOwner value from an entry is not the same as deleting the ACI or entryOwner. It is possible for an entry to contain an ACI or entryOwner with no values. In this case, nothing is returned to the client when querying the ACI or entryOwner and the setting propagates to the descendent nodes until it is overridden. To prevent dangling entries that nobody can access, the directory administrator always has full access to an entry even if the entry has a null ACI or entryOwner value.
The effective ACI or entryOwner values can be retrieved by simply specifying the desired ACL or entryOwner attributes in a search, for example,
ldapsearch -b "cn=object A, o=ibm" -s base "objectclass=*"
aclentry aclpropagate aclsource entryowner ownerpropagate ownersource
returns all ACL or entryOwner information that is used in access evaluation on object A. Note that the returned values might not look exactly the same as they are first defined. The values are the equivalent of the original form.
Follow these steps to use the Directory Management Tool utility to work with ACLs.
An entry can either have an explicitly defined ACL or inherit an ACL from a parent object.
The ACL panel contains two tabs:
After modifying the settings on the ACLs and Owners tabs, click OK to add the ACL to the selected entry.
The ACLs tab contains four sections:
If the ACL source is the default, select:
If the ACL source is not the default, select:
Each security class has permissions associated with it.
Additionally, you may specify permissions based on the attribute instead of the security class to which the attribute belongs.
The Owners tab contains two sections:
If the Owner source is the default, select:
If the ACL source is not the default, select:
A group is a list, a collection of names. A groups can be used in aclentry and entryowner attributes to control access or in application-specific uses such as a mailing list; see Access Control Lists. Groups can be defined as either static, dynamic, or nested.
A static group defines each member individually using the structural objectclass groupOfNames, groupOfUniqueNames, accessGroup, or accessRole; or the auxiliary objectclass ibm-staticgroup. These objectclasses require the attribute member (or uniqueMember in the case of groupOfUniqueNames). A static group using these structural objectclasses must have at least one member; it cannot be empty. A static group may also be defined using the auxiliary objectclass: ibm=staticGroup, which does not require the member attribute, and therefore may be empty.
A typical group entry is:
DN: cn=Dev.Staff,ou=Austin,c=US objectclass: accessGroup cn: Dev.Staff member: cn=John Doe,o=IBM,c=US member: cn=Jane Smith,o=IBM,c=US member: cn=James Smith,o=IBM,c=US
Each group object contains a multivalued attribute consisting of member DNs.
Upon deletion of an access group, the access group is also deleted from all ACLs to which it has been applied.
A dynamic group defines its members differently than a static group. Instead of listing them individually, the dynamic group defines its members using an LDAP search. The dynamic group uses the structural objectclass groupOfURLs (or auxiliary objectclass ibm-dynamicGroup) and the attribute, memberURL to define the search using a simplified LDAP URL syntax.
ldap:///<base DN of search> ? ? <scope of search> ? <searchfilter>
The search for dynamic members is always internal to the server, so unlike a full ldap URL, a host name and port number is never specified, and the protocol is always ldap (never ldaps). The memberURL attribute may contain any kind of URL, but the server only uses memberURLs beginning with ldap:/// to determine dynamic membership.
A single entry in which the scope defaults to base and the filter defaults to objectclass=*:
ldap:///cn=John Doe, cn=Employees, o=Acme, c=US
All entries that are 1-level below cn=Employees, and the filter defaults to objectclass=*:
ldap:///cn=Employees, o=Acme, c=US??one
All entries that are under o-Acme with the objectclass=person:
ldap:///o=Acme, c=US??sub?objectclass=person
Depending on the object classes you use to define user entries, those entries might not contain attributes which are appropriate for determining group membership. You can use the auxiliary object class, ibm-dynamicMember, to extend your user entries to include the ibm-group attribute. This attribute allows you to add arbitrary values to your user entries to serve as targets for the filters of your dynamic groups. For example:
The members of this dynamic group are entries directly under the cn=users,ou=Austin entry that have an ibm-group attribute of GROUP1:
dn: cn=GROUP1,ou=Austin objectclass: groupOfURLs cn: GROUP1 memberURL: ldap:///cn=users,ou=Austin??one?(ibm-group=GROUP1)
Here is an example member of cn=GROUP1,ou=Austin:
dn: cn=Group 1 member, cn=users, ou=austin objectclass: person objectclass: ibm-dynamicMember sn: member userpassword: memberpassword ibm-group: GROUP1
The nesting of groups enables the creation of hierarchical relationships that can be used to define inherited group membership. A nested group is defined as a child group entry whose DN is referenced by an attribute contained within a parent group entry. A parent group is created by extending one of the structural group object classes (groupOfNames, groupOfUniqueNames, accessGroup, accessRole, or groupOfURLs) with the addition of the ibm-nestedGroup auxiliary object class. After nested group extension, zero or more ibm-memberGroup attributes may be added, with their values set to the DNs of nested child groups. For example:
dn: cn=Group 2, cn=Groups, o=IBM, c=US objectclass: groupOfNames objectclass: ibm-nestedGroup objectclass: top cn: Group 2 description: Group composed of static, and nested members. member: cn=Person 2.1, cn=Dept 2, cn=Employees, o=IBM, c=US member: cn=Person 2.2, cn=Dept 2, cn=Employees, o=IBM, c=US ibm-memberGroup: cn=Group 8, cn=Nested Static, cn=Groups, o=IBM, c=US
The introduction of cycles into the nested group hierarchy is not allowed. If it is determined that a nested group operation results in a cyclical reference, either directly or through inheritance, it is considered a constraint violation and therefore, the update to the entry fails.
Any of the structural group object classes mentioned can be extended such that group membership is described by a combination of static, dynamic, and nested member types. For example:
dn: cn=Group 10, cn=Groups, o=IBM, c=US objectclass: groupOfURLs objectclass: ibm-nestedGroup objectclass: ibm-staticGroup objectclass: top cn: Group 10 description: Group composed of static, dynamic, and nested members. memberURL: ldap:///cn=Austin, cn=Employees, o=IBM, c=US??one?objectClass=person ibm-memberGroup: cn=Group 9, cn=Nested Dynamic, cn=Groups, o=IBM, c=US member: cn=Person 10.1, cn=Dept 2, cn=Employees, o=IBM, c=US member: cn=Person 10.2, cn=Dept 2, cn=Employees, o=IBM, c=US
Two operational attributes can be used to query aggregate group membership. For a given group entry, the ibm-allMembers operational attribute enumerates the aggregate set of group membership, including static, dynamic, and nested members, as described by the nested group hierarchy. For a given user entry, the ibm-allGroups operational attribute enumerates the aggregate set of groups, including ancestor groups, to which that user has membership.
A requester may only receive a subset of the total data requested, depending on how the ACLs have been set on the data. Anyone can request the ibm-allMembers and ibm-allGroups operational attributes, but the data set returned only contains data for the LDAP entries and attributes that the requester has access rights to. The user requesting the ibm-allMembers or ibm-allGroups attribute must have access to the member or uniquemember attribute values for the group and nested groups in order to see static members, and must be able to perform the searches specified in the memberURL attribute values in order to see dynamic members. For examples:
For this example, m1 and m2 are in the member attribute of g2. The ACL for g2 allows user1 to read the member attribute, but user 2 does not have access to the member attribute. The entry LDIF for the g2 entry is as follows:
dn: cn=g2,cn=groups,o=ibm,c=us objectclass: accessGroup cn: g2 member: cn=m1,cn=users,o=ibm,c=us member: cn=m2,cn=users,o=ibm,c=us aclentry: access-id:cn=user1,cn=users,o=ibm,c=us:normal:rsc aclentry: access-id:cn=user2,cn=users,o=ibm,c=us:normal:rsc:at.member:deny:rsc
The g4 entry uses the default aclentry, which allows both user1 and user2 to read its member attribute. The LDIF for the g4 entry is as follows:
dn: cn=g4, cn=groups,o=ibm,c=us objectclass: accessGroup cn: g4 member: cn=m5, cn=users,o=ibm,c=us
The g5 entry is a dynamic group, which gets its two members from the memberURL attribute. The LDIF for the g5 entry is as follows:
dn: cn=g5, cn=groups,o=ibm,c=us objectclass: container objectclass: ibm-dynamicGroup cn: g5 memberURL: ldap:///cn=users,o=ibm,c=us??sub?(|(cn=m3)(cn=m4))
The entries m3 and m4 are members of group g5 because they match the memberURL The ACL for the m3 entry allows both user1 and user2 to search for it. The ACL for the m4 entries doesn't allow user2 to search for it. The LDIF for m4 is as follows:
dn: cn=m4, cn=users,o=ibm,c=us objectclass:person cn: m4 sn: four aclentry: access-id:cn=user1,cn=users,o=ibm,c=us:normal:rsc aclentry: access-id:cn=user2,cn=users,o=ibm,c=us
ldapsearch -D cn=user1,cn=users,o=ibm,c=us -w user1pwd -s base -b cn=g1,
cn=groups,o=ibm,c=us objectclass=* ibm-allmembers
cn=g1,cn=groups,o=ibm,c=us
ibm-allmembers: CN=M1,CN=USERS,O=IBM,C=US
ibm-allmembers: CN=M2,CN=USERS,O=IBM,C=US
ibm-allmembers: CN=M3,CN=USERS,O=IBM,C=US
ibm-allmembers: CN=M4,CN=USERS,O=IBM,C=US
ibm-allmembers: CN=M5,CN=USERS,O=IBM,C=US
ldapsearch -D cn=user2,cn=users,o=ibm,c=us -w user2pwd -s base -b cn=g1,
cn=groups,o=ibm,c=us objectclass=* ibm-allmembers
cn=g1,cn=groups,o=ibm,c=us
ibm-allmembers: CN=M3,CN=USERS,O=IBM,C=US
ibm-allmembers: CN=M5,CN=USERS,O=IBM,C=US
ldapsearch -D cn=user2,cn=users,o=ibm,c=us -w user2pwd -s base -b cn=m3,
cn=users,o=ibm,c=us objectclass=* ibm-allgroups
cn=m3,cn=users,o=ibm,c=us
ibm-allgroups: CN=G1,CN=GROUPS,O=IBM,C=US
ldapsearch -D cn=user2,cn=users,o=ibm,c=us -w user2pwd -s base -b
cn=m1,cn=users,o=ibm,c=us objectclass=* ibm-allgroups
cn=m1,cn=users,o=ibm,c=us
Role-based authorization is a conceptual complement to the group-based authorization, and is useful in some cases. As a member of a role, you have the authority to do what is needed for the role in order to accomplish a job. Unlike a group, a role comes with an implicit set of permissions. There is not a built-in assumption about what permissions are gained (or lost) by being a member of a 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 which are to be used in access control must have an objectclass of 'AccessRole'. The 'Accessrole' objectclass is a subclass of the 'GroupOfNames' objectclass.
For example, if there are a collection of DNs such as 'sys admin', your first reaction may be to think of them as the 'sys admin group' (since groups and users are the most familiar types of privilege attributes). However, since there are a set of permissions that you would expect to receive as a member of 'sys admin' the collection of DNs may be more accurately defined as the 'sys admin role'.
Each directory entry has a set of attributes associated with it through it's object class. You can create, edit, or delete attributes to suit the needs of your organization.
If you have not done so already, expand the Schema category in the navigation area, then expand Attributes.
The following example adds an attribute type definition for an attribute called "myAttribute", with Directory String syntax and Case Ignore Equality matching. 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> -f myschema.ldif
where the myschema.ldif file contains:
dn: cn=schema
changetype: add
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.
Any part of a definition can be changed before you have added entries that use the attribute.
If you have not done so already, expand the Schema category in the navigation area, then expand Attributes.
See Adding an attribute help for additional information about attributes.
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> -f myschemachange.ldif
Where the myschemachange.ldif file contains:
dn: cn=schema
changetype: replace
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 )
To remove an attribute from the schema, you can delete the definition, if you have no data in the directory that includes this attribute.
If you have not done so already, expand the Schema category in the navigation area, then expand Attributes.
ldapmodify -D <admindn> -w <adminpw> -f myschemadelete.ldif
Where the myschemadelete.ldif file includes:
dn: cn=schema
changetype: delete
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 )
Binary attributes, such as images, are indicated by
to the left of the attribute field.
Because binary attributes cannot be displayed, if an attribute contains binary data, the field displays **** BINARY DATA ****. If the attribute contains multiple values, the field displays as a drop-down list. Click the icon to work with binary attributes.
If the attribute has no data, a browse window is displayed. Select the file that contains the binary data and click Import.
If the attribute already contains data, you are prompted to either Update the existing data or Export the existing data to a file.
An object class is a set of attributes used to describe an object. For example, the object class tempEmployee 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.
If you have not done so already, expand the Schema category in the navigation area, then expand Object classes.
If you have not done so already, expand the Schema category in the navigation area, then expand Object classes.
If you have not done so already, expand the Schema category in the navigation area, then expand Attributes.
View the log file to review error messages, directory and schema modifications, and server connection information for the current server. Servers are displayed as tabs in the navigation area. The current server is the selected tab in the navigation area.
You can perform the following operations with directory entries:
There are two options for searching the directory tree:
Both search options are accessible by expanding the Directory tree category in the navigation area, then expanding Search tree.
A simple search uses a default search criteria:
To perform a simple search:
An advanced search enables you to specify search constraints and enable search filters. Use the Simple search to use default search criteria.
After performing a search, click Save search to save the search criteria. Saved searches are displayed under the Search tree category in the navigation area. Clicking a saved search in the navigation area start the search and display the search results.
To edit a saved search:
To delete a saved search:
If you have not done so already, expand the Directory tree category in the navigation area.
The Current definition tab shows the object classes, required attributes, and optional attributes based on the selections on the Object class tab.
Depending on the Entry type you selected a series of tabs is displayed on this panel. Most entry types display an Attributes tab. The User entry displays three tabs: Business, Personal, and User. The Group entry displays two tabs: Group and Other.
The pencil icon indicates the attribute can have multiple values, for example,
to accommodate a maiden and married last name. To add multiple values
to an attribute, click the pencil icon, then add one value per line.
The binary attribute icon indicates the syntax for the attribute is binary,
for example, an image. See Binary attributes for additional information.
You can move the mouse over the field name or field to display the attribute syntax, for example, IA5 String - case-sensitive string.
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 tree category in the navigation area.
If you have not done so already, expand the Directory tree category in the navigation area.
The Edit entry panel contains tabs for the attributes associated with the object class. The Summary tab displays the completed attributes for that entry. Users and Groups have tabs specific to the User and Group entry types as follows:
The Users entry contains five tabs:
The Groups entry contains tabs unique to the Group entry. See Groups for additional information.
Click Refresh List to list all unique members of this group.
Click Refresh List to display the dynamic and nested groups to which this entry belongs. This is an information list only and not editable from this window. After clicking on the Refresh List button, the label for the list changes to All Group Memberships.
To change static group membership, click Edit Static Groups. After editing static group membership, if any changes were made, the label for the list is changed to Static Group Memberships and the list displays the updated static group memberships.
The pencil icon indicates the attribute can have multiple values, for example,
to accommodate a maiden and married last name. To add multiple values
to an attribute, click the pencil icon, then add one value per line.
If an attribute contains multiple values, the field displays as a drop-down
list.
The binary attribute icon indicates the syntax for the attribute is binary,
for example, an image. If a binary attribute contains multiple values,
the field displays as a drop-down list. See Binary attributes for additional information.
You can move the mouse over the field name or field to display the attribute syntax, for example, IA5 String - case-sensitive string.
If you have not done so already, expand the Directory tree category in the navigation area.
icon to the left of their entry in the directory tree.
During configuration, you might experience some problems with the IBM Directory configuration programs. There are some extra debugging steps that can help you and IBM support teams determine the cause of these problems.
There are three configuration programs in the IBM Directory product. Two are run from a command line, and one is GUI-based. The configuration programs are:
These configuration programs support three main functions:
The configuration of the first two options, Admin DN and the Web server configuration file, are very straightforward. Generally, the only reasons the configuration of the Admin DN fails are if the IBM Directory configuration file ( <install dir>/etc/slapd32.conf ) has had the permissions accidentally changed, or if the user enters an invalid DN. Likewise, the configuration of the Web server usually has no problems as long as the program or the user can locate the correct Web server configuration file. (The program attempts to locate the file and enters the filename into the entryfield, but the user has the option of changing it if it is not correct.)
This leaves the most problematic option, the database configuration/unconfiguration. Because there are so many variables at play during configuration, errors can occur. Some of the factors that can affect this option are:
If the database configuration fails, the bottom-line question for the user is, "What failed, and how do I fix it?". The following sections describe sources of output that can be used to debug configuration problems.
There are several "standard" sources of information available to the user:
All of the config programs are either started from a console command line prompt (ldapcfg, ldapucfg) or open a background console (ldapxcfg). As the database configuration progresses, status messages (and limited error messages) are displayed in the associated console window. If a problem occurs, the user should copy these messages to the system clipboard and then save them in a file for the support teams.
If the error is a direct error from DB2, then DB2 often creates message/error files in the /tmp directory (on UNIX platforms). If the user has a database configuration problem on UNIX systems , they need to examine all of the files in the /tmp directory that were created around the time of the attempted configuration. On Windows systems , examine any DB2 error logs in your DB2 install directory under the directory named for the instance you were trying to configure. For example, if your were trying to create the default ldapdb2 instance and database, and if your DB2 was installed in D:\sqllib, then you need to examine the files in the D:\sqllib\ldadb2 directory if it exists. Especially look for and examine the 'db2diag.log' file in that directory.
IBM Directory logs most configuration errors in the file 'ldacfg.out'. On UNIX platforms, this file can be found in the /tmp directory. On Windows platforms, this file is created in the root directory of the drive you ran configuration from.
There are two more sources of output that can be used to debug configuration problems. Both of them are initiated by setting environment variables before running the configuration. For both of these debug options, it is strongly recommended that your console window be set to scrollable so that any messages that scroll off the screen can be seen later.
JAVA_DEBUG=1
On UNIX platforms, use export JAVA_DEBUG=1. This causes certain Java debug information built into the code to be displayed on stdout (the console).
LDAP_DBG =1
On UNIX platforms, use export LDAP_DBG=1. This causes a debug file to be created for the IBM support and development teams. The file name that is created is dbg.log.
On the Windows NT and Windows 2000 platforms, dbg.log is created in the root directory ( \ ) of the drive from which you run the configuration program. On UNIX platforms, dbg.log is created in the /tmp directory.
The slapd command has two parameters on UNIX systems and an additional two parameters on Windows systems.
Additional parameters for Windows systems:
If the error logs do not provide enough information to resolve a problem, you can run the IBM Directory server in a special debug mode that generates very detailed information. The server executable slapd must be run from a command prompt to enable debug output. The syntax is as follows:
ldtrc on slapd -h bitmaskwhere the specified bitmask value determines which categories of debug output are generated.
| Hex | Decimal | Value | Description |
|---|---|---|---|
| 0x0001 | 1 | LDAP_DEBUG_TRACE | Entry and exit from routines |
| 0x0002 | 2 | LDAP_DEBUG_PACKETS | Packet activity |
| 0x0004 | 4 | LDAP_DEBUG_ARGS | Data arguments from requests |
| 0x0008 | 8 | LDAP_DEBUG_CONNS | Connection activity |
| 0x0010 | 16 | LDAP_DEBUG_BER | Encoding and decoding of data |
| 0x0020 | 32 | LDAP_DEBUG_FILTER | Search filters |
| 0x0040 | 64 | LDAP_DEBUG_MESSAGE | Messaging subsystem activities and events |
| 0x0080 | 128 | LDAP_DEBUG_ACL | Access Control List activities |
| 0x0100 | 256 | LDAP_DEBUG_STATS | Operational statistics |
| 0x0200 | 512 | LDAP_DEBUG_THREAD | Threading statistics |
| 0x0400 | 1024 | LDAP_DEBUG_REPL | Replication statistics |
| 0x0800 | 2048 | LDAP_DEBUG_PARSE | Parsing activities |
| 0x1000 | 4096 | LDAP_DEBUG_PERFORMANCE | Relational backend performance statistics |
| 0x1000 | 8192 | LDAP_DEBUG_RDBM | Relational backend activities (RDBM) |
| 0x4000 | 16384 | LDAP_DEBUG_REFERRAL | Referral activities |
| 0x8000 | 32768 | LDAP_DEBUG_ERROR | Error conditions |
| 0xffff | 65535 | ALL |
|
| 0x7fffffff | 2147483647 | LDAP_DEBUG_ANY | All levels of debug |
For example, specifying a bitmask value of "65535" turns on full debug output and generates the most complete information.
When you are finished, issue the following command at a command prompt:
ldtrc off
It is recommended that you contact IBM Service for assistance with interpreting of the debug output and resolving of the problem.
Index rules attached to attributes make it possible to retrieve information faster. If only the attribute is given, all possible indexes are maintained. IBM Directory provides the following indexing rules:
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 three possible types of indexing rules are related to the operations applied in the search filter.
For example:
"cn = John Doe" "sn >= Doe"
For example:
"sn ~= doe"
For example:
"sn = McC*" "sn = *baugh" "cn = J*Doe"
At a minimum, it is recommended that you specify Equal indexing on any attributes that are to be used in search filters.
The following key-management program is provided with IBM's Global Security Kit (GSKit):
export LIBPATH=/usr/ldap/java/bin:/usr/ldap/java/bin/classic:$LIBPATH
Use gsk5ikm 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 gsk5ikm include:
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:
To create a public-private key pair and request a certificate:
gsk5ikm
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.
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:
To change a key database password:
To show information about a key, such as its name, size or whether it is a trusted root:
To delete a key:
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:
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:
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:
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:
To import a key into a key ring:
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:
To designate 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:
To remove the trusted root status of a key:
To create a certificate request for an existing key:
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.
The gsk5ikm program can be used to migrate an existing keyring file, as created with mkkf, to the format used by gsk5ikm.
To migrate a keyring file:
This documentation describes the LDAP Data Interchange Format (LDIF), as used by the ldapmodify, ldapsearch and ldapadd utilities. The LDIF specified here is also supported by the server utilities provided with the IBM Directory.
LDIF is used to represent LDAP entries in text form. The basic form of an LDIF entry is:
dn: <distinguished name> <attrtype> : <attrvalue> <attrtype> : <attrvalue> ...
A line can be continued by starting the next line with a single space or tab character, for example:
dn: cn=John E Doe, o=University of Higher
Learning, c=US
Multiple attribute values are specified on separate lines, for example:
cn: John E Doe
cn: John Doe
If an <attrvalue> contains a non-US-ASCII character, or begins with a space or a colon ':', the <attrtype> is followed by a double colon and the value is encoded in base-64 notation. For example, the value " begins with a space" would be encoded like this:
cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U=
Multiple entries within the same LDIF file are separated by a blank line. Multiple blank lines are considered a logical end-of-file.
Here is an example of an LDIF file containing three entries.
dn: cn=John E Doe, o=University of High
er Learning, c=US
cn: John E Doe
cn: John Doe
objectclass: person
sn: Doe
dn: cn=Bjorn L Doe, o=University of High
er Learning, c=US
cn: Bjorn L Doe
cn: Bjorn Doe
objectclass: person
sn: Doe
dn: cn=Jennifer K. Doe, o=University of High
er Learning, c=US
cn: Jennifer K. Doe
cn: Jennifer Doe
objectclass: person
sn: Doe
jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD
A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ
ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG
...
The jpegPhoto in Jennifer Jensen's entry is encoded using base-64. The textual attribute values can also be specified in base-64 format. However, if this is the case, the base-64 encoding must be in the code page of the wire format for the protocol (that is, for LDAP V2, the IA5 character set and for LDAP V3, the UTF-8 encoding).
The client utilities (ldapmodify and ldapadd) have been enhanced to recognize the latest version of LDIF, which is identified by the presence of the "version: 1" tag at the head of the file. Unlike the original version of LDIF, the newer version of LDIF supports attribute values represented in UTF-8 (instead of the very limited US-ASCII).
However, manual creation of an LDIF file containing UTF-8 values may be difficult. In order to simplify this process, a charset extension to the LDIF format is supported. This extension allows an IANA character set name to be specified in the header of the LDIF file (along with the version number). A limited set of the IANA character sets are supported. See IANA Character Sets Supported by Platform for the specific charset values that are supported for each operating system platform.
The version 1 LDIF format also supports file URLs. This provides a more flexible way to define a file specification. File URLs take the following form:
attribute:< file:///path (where path syntax depends on platform)
For example, the following are valid file Web addresses:
jpegphoto:< file:///d:\temp\photos\myphoto.jpg (DOS/Windows style paths)
jpegphoto:< file:///etc/temp/photos/myphoto.jpg (Unix style paths)
You can use the optional charset tag so that the utilities will automatically convert from the specified character set to UTF-8 as in the following example:
version: 1 charset: ISO-8859-1 dn: cn=Juan Griego, o=University of New Mexico, c=US cn: Juan Griego sn: Griego description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvd title: Associate Dean title: [title in Spanish] jpegPhoto:> file:///usr/local/photos/jgriego.jpg
In this instance, all values following an attribute name and a single colon are translated from the ISO-8859-1 character set to UTF-8. Values following an attribute name and a double colon (such as description:: V2hhdCBhIGNhcm... ) must be base-64 encoded, and are expected to be either binary or UTF-8 character strings. Values read from a file, such as the jpegPhoto attribute specified by the Web address in the previous example, are also expected to be either binary or UTF-8. No translation from the specified "charset" to UTF-8 is done on those values.
In this example of an LDIF file without the charset tag, content is expected to be in UTF-8, or base-64 encoded UTF-8, or base-64 encoded binary data:
# IBM Directorysample LDIF file # # The suffix "o=IBM, c=US" should be defined before attempting to load # this data. version: 1 dn: o=IBM, c=US objectclass: top objectclass: organization o: IBM dn: ou=Austin, o=IBM, c=US ou: Austin objectclass: organizationalUnit seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US
This same file could be used without the version: 1 header information, as in previous releases of the IBM Directory:
# IBM Directorysample LDIF file # # The suffix "o=IBM, c=US" should be defined before attempting to load # this data. dn: o=IBM, c=US objectclass: top objectclass: organization o: IBM dn: ou=Austin, o=IBM, c=US ou: Austin objectclass: organizationalUnit seealso: cn=Linda Carlesberg, ou=Austin, o=IBM, c=US
The following table defines the set of IANA-defined character sets that can be defined for the charset tag in a Version 1 LDIF file, on a per-platform basis. The value in the left-most column defines the text string that can be assigned to the charset tag. An "X" indicates that conversion from the specified charset to UTF-8 is supported for the associated platform, and that all string content in the LDIF file is assumed to be represented in the specified charset. "n/a" indicates that the conversion is not supported for the associated platform.
String content is defined to be all attribute values that follow an attribute name and a single colon.
See IANA Character Sets for more information about
IANA-registered character sets.
| Character | Conversion Supported | |||
|---|---|---|---|---|
| Set Name | NT | AIX | Solaris | Linux, Linux_390, HP-UX |
| ISO-8859-1 | X | X | X | X |
| ISO-8859-2 | X | X | X | X |
| ISO-8859-5 | X | X | X | X |
| ISO-8859-6 | X | X | X | X |
| ISO-8859-7 | X | X | X | X |
| ISO-8859-8 | X | X | X | X |
| ISO-8859-9 | X | X | X | X |
| ISO-8859-15 | NA | X | X | NA |
| IBM437 | X | NA | NA | NA |
| IBM850 | X | X | NA | NA |
| IBM852 | X | NA | NA | NA |
| IBM857 | X | NA | NA | NA |
| IBM862 | X | NA | NA | NA |
| IBM864 | X | NA | NA | NA |
| IBM866 | X | NA | NA | NA |
| IBM869 | X | X | NA | NA |
| IBM1250 | X | NA | NA | NA |
| IBM1251 | X | NA | NA | NA |
| IBM1253 | X | NA | NA | NA |
| IBM1254 | X | NA | NA | NA |
| IBM1255 | X | NA | NA | NA |
| IBM1256 | X | NA | NA | NA |
| TIS-620 | X | X | NA | NA |
| EUC-JP | NA | X | X | X |
| EUC-KR | NA | X | X | NA |
| EUC-CN | NA | X | X | NA |
| EUC-TW | NA | X | X | NA |
| Shift-JIS | X | X | X | X |
| KSC | X | X | NA | NA |
| GBK | X | X | X | NA |
| Big5 | X | X | X | NA |
This information was developed for products and services offered in the U.S.A. IBM might not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of LicensingFor license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation LicensingThe following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM CorporationSuch information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may vary.
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:
| AIX | DB2 | IBM | OS/400 | SecureWay | World Registry | z/OS |
Microsoft(R), MS-DOS, Windows, and Windows NT are registered trademarks of Microsoft Corporation
UNIX is a registered trademark of The Open Group.
Other company, product, and service names may be trademarks or service marks of others.
Use this section to locate definitions of some of the IBM Directory product terms
Aliases Objects are of 'objectclass=aliasObject'. The mandatory attribute in this class, 'aliasedObjectName', contains the full dn of another directory object (the one to which the alias refers).
By default, aliases objects are not dereferenced during a search operation. The client may request dereferencing using a flag on the command line. Aliases may be dereferenced when locating the base entry of the search. If the object specified as the base is an alias object, the object will be derefenced before beginning the search.
For example, an object with dn "cn=personOfTheWeek, o=Corporation, c=US" which has the attribute aliasedObjectName: "cn=personA, o=Corporation,c=US". With 'deref finding' set, a search base of "cn=personOfTheWeek, o=Corporation, c=US" is dereferenced to "cn=personA, o=Corporation,c=US". This now becomes the base for the search.
Another possibility is to dereference aliases during searching. In this case, the dn used as the base is the one given by the client, but alias entries found during the search are dereferenced.
An example of this might be a search for "cn=*week*" with a base of o=Corporation, c=US". While the located Node is "cn=personOfTheWeek, o=Corporation, c=US" this object would be dereferenced and the entry "cn=personA, o=Corporation,c=US" is returned as the search result.
A dereference of 'all' might also be used. This means that alias entries are dereferenced both when locating the search base and when objects are found during the search operation.
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
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.
The search expressions can be used in combination with existing group attributes.
Normal groups have an object class of 'GroupOfNames', 'GroupOfUniqueNames' or a user defined group. Access control groups have an object class of 'AccessGroup'.
Each group object contains a multivalued attribute consisting of member DNs. Groups cannot contain group DNs.
The LDIF tool ldif is a shell-accessible utility that converts arbitrary data values to LDIF. It reads input values from standard input and produces LDIF.
caseExactIA5Match caseExactMatch caseExactOrderingMatch caseExactSubstringsMatch caseIgnoreIA5Match caseIgnoreMatch caseIgnoreOrderingMatch caseIgnoreSubstringsMatch distinguishedNameMatch distinguishedNameOrderingMatch generalizedTimeMatch generalizedTimeOrderingMatch integerFirstComponentMatch integerMatch objectIdentifierFirstComponentMatch objectIdentifierMatch octetStringMatch telephoneNumberMatch telephoneNumberSubstringsMatch uTCTimeMatch
indicates the attribute can have multiple values, for example, to accommodate
a maiden and married last name. To add multiple values to an attribute,
click the pencil icon, then add one value per line. If an attribute
contains multiple values, the field displays as a drop-down list.
The general format for a referral is: ldap[s]://hostname:port. Typically the format for a referral to a nonsecure server is: ldap://hostname:389 and to a secure SSL server is: ldaps://hostname:636. See Referrals for additional information.
IBM Attribute Type Description
Matching Rule Description
Name Form Description
Attribute Type Description
Object Class Description
DIT Structure Rule Description
DIT Content Rule Description
LDAP Syntax Description
OID
Matching Rule Use Description
Boolean - TRUE/FALSE
Binary - octet string
INTEGER - integral number
Generalized Time
IA5 String - case-sensitive string
Directory String - case-insensitive
string
UTC time
Telephone Number
DN - distinguished name