Corrections and clarifications to IBM Tivoli Directory Server 6.0 documentation

Resolving The Problem

Corrections and updates to documentation:

• Compatibility Specifications

The following standards are implemented in IBM Tivoli Directory Server 6.0:

• RFC 1274 The COSINE and Internet X.500 Schema
• RFC 1777 Lightweight Directory Access Protocol (V2)
• RFC 1778 String Representation of Standard Attribute Syntax's
• RFC 1779 String Representation of Distinguished Names
• RFC 1823 LDAP Application Program Interface (V2)
• RFC 2052 A DNS RR for specifying the location of services (DNS SRV)
• RFC 2219 Use of DNS Aliases for Network Services
• RFC 2222 Simple Authentication and Security Layer (SASL)
• RFC 2247 Using Domains in LDAP/X.500 Distinguished Names
• RFC 2251 Lightweight Directory Access Protocol (V3)
• RFC 2252 Lightweight Directory Access Protocol (V3): Attribute Syntax Definitions
• RFC 2253 Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names
• RFC 2254 The String Representation of LDAP Search Filters
• RFC 2255 The LDAP URL Format
• RFC 2256 A Summary of the X.500(96) User Schema for use with LDAPv3
• RFC 2596 Use of Language code in LDAP
• RFC 2696 LDAP Control Extension for Simple Paged Results Manipulation
• RFC 2829 Authentication Methods for LDAP
• RFC 2830 (V3) Extension for Transport Layer Security (TLS)
• RFC 2831 Using DIGEST authentication as a SASL Mechanism
• RFC 2849 The LDAP Data Interchange Format (LDIF) - Technical Specification
• RFC 2891 LDAP Control Extension for Server Side Sorting of Search Results
• The Open Group schema for liPerson and liOrganization (NAC/LIPS)
• RFC 2307 (Directory Schema Only) – Posix Unix Account authentication

• Release Notes

Supported languages:

Translated server messages are provided on all supported operating systems. If you want to use the server in languages other than English, you must install language packs for the languages you want to use. (See the Installation and Configuration Guide for instructions.)

The following language versions are provided on all supported operating systems: German, French, Italian, Spanish, Japanese, Korean, Portuguese, Simplified Chinese, Traditional Chinese.

On AIX only, the following additional language versions are available: Czech, Hungarian, Polish, Russian, Slovak.

Note: You do not need to install language packs for the following:

• The Web Administration Tool.
• The client, unless you want to use the idslink and idsrmlink commands and you want messages from the commands displayed in a language other than English. For information about the idslink and idsrmlink commands, see the Installation and Configuration Guide.

• Installation and Configuration Guide:

System Requirements:

Updates to the system requirements and supported operating systems for IBM Tivoli Directory Server 6.0 can be found at the following Web address: http://www.ibm.com/software/tivoli/products/directory-server/platforms.html

If an IBM Tivoli Directory Server 6.0 fix pack causes a change to the system requirements or supported operating systems, these updates are documented in the Readme file for the fix pack.

Migration from IBM Directory Server 5.2 on AIX systems:
(Work item XX02235; PMR # 06042; 033; 000)

In "Chapter 4. Migration from previous releases," use the section called "Migration from IBM Directory Server 4.1 or 5.1 on non-AIX systems or IBM Tivoli Directory Server 5.2 on all Systems" if you are migrating from IBM Tivoli Directory Server Version 5.2 on an AIX system.
However, in the Post-installation steps in this section, step 7, you are referred to the section called "Migrating your database instance and databases." In this section, under "On AIX systems," under the first bullet ("If your database is DB2 8.1"), step 1 tells you to update your database instance to a 64-bit width.

This step is not needed because your IBM Tivoli Directory Server 5.2 database was a 64-bit database instance.

Replacing or installing a new version of DB2 on AIX or Linux:
(APAR # IO03226)

In "Chapter 4. Migration from previous releases," in the section called "Database tasks before, during, and after migration," in the subsection "Replacing or installing a new version of DB2," the section called "On AIX and Linux systems:" should be changed to read as follows:

On AIX and Linux systems:

To install a supported version of DB2:

• If your version of DB2 is Workgroup Server Edition 8.1:

1. Uninstall DB2 Workgroup Server Edition 8.1.
2. Delete all the IPC objects owned by the instance_name instance, as follows:

a. At the command prompt, type:

ipcs -a | grep instance_name

This displays a list of all object IDs (message queues, shared memory, and semaphores) owned by instance instance_name.

b. For each message queue object owned by instance_name, type:

ipcrm -q object_id

c. For each semaphore owned by instance_name, type:

ipcrm -s object_id

3. Install DB2 Enterprise Server Edition 8 Fix Pack 8 refresh.


• If your version of DB2 is Enterprise Server Edition 8.1:

Install DB2 Enterprise Server Edition 8 Fix Pack 8 refresh. (Uninstallation of Enterprise Server Edition 8.1 is not required.)

• If your version of DB2 is 7.2:

Install DB2 Enterprise Server Edition 8 Fix Pack 8 refresh on top of DB2 7.2.

Incorrect default for ibm-slapdPWEncryption attribute:

In "Appendix P. IBM Tivoli Directory Server configuration schema," the default setting for the ibm-slapdPWEncryption attribute is listed as "none." The default value is actually aes256.

Incorrect statement about local loopback service:
(Work item XX02183)

The description of the idscfgdb command contains the following paragraph:

The idscfgdb command configures the database for a directory server instance. The database instance must already exist and for AIX, Linux, Solaris, and HP-UX systems, the local loopback service must be registered in the /etc/services file. Otherwise, the command fails.

The paragraph should say:

The idscfgdb command configures the database for a directory server instance. The idsicrt command must have already run successfully to create the database instance. In addition, the database instance owner must be set up correctly. (See "Appendix D. Setting up users and groups: directory server instance owner, database instance owner, and database owner" for information.) Otherwise, the command fails.

The same paragraph is in the description of the idscfgdb command in the Administration Guide. It is also incorrect.

Clarification to Appendix E. Synchronizing two-way cryptography between server instances:

See "Clarification to Appendix I. Synchronizing two-way cryptography between server instances:" in the Administration Guide section.

Incorrect log paths in Appendix P:
(Work item #XX02669, PMR #90633,999,000, APAR #IO04283)

Incorrect paths are given for logs in "Appendix P. IBM Tivoli Directory Server configuration schema," in the "Attributes" section:

• In "ibm-slapdBulkloadErrors" the default path for the bulkload error log should be:
• top_level_drive:\idsslapd-ds_inst_name\logs\bulkload.log for Windows systems
• ds_inst_owner_home/idsslapd-ds_inst_name/logs/bulkload.log for AIX, Linux, Solaris, and HP-UX systems
• In "ibm-slapdCLIErrors" the default path for the DB2 error log should be:
• top_level_drive:\idsslapd-ds_inst_name\logs\db2cli.log for Windows systems
• ds_inst_owner_home/idsslapd-ds_inst_name/logs/db2cli.log for AIX, Linux, Solaris, and HP-UX systems

• Administration Guide:

Managing the IBM Directory schema

Technote #1244308: Size limits for custom attributes gives the information on maximum size allowed for custom attributes.

Setting password policy

The pwdCheckSyntax attribute must be set in order for password syntax checking to occur. See Technote #1303141: Password Policy Attributes for details and other attributes that are dependent upon this attribute's setting.

Creating unique attributes using the command line
(Work item XX03880)

There is an error in the sample LDIF used to designate that an attribute must have unique values:

dn: cn=uniqueattributes,cn=localhost changetype: add ibm-UniqueAttributeTypes: sn objectclass: top objectclass: ibm-UniqueAttributeTypes

There is no objectclass "ibm-UniqueAttributeTypes". The corrected sample should read:

dn: cn=uniqueattributes,cn=localhost changetype: add ibm-UniqueAttributeTypes: sn objectclass: top objectclass: ibm-UniqueAttributes

Missing word in IP address description:
(Work item XX02379)

In "Chapter 9. Basic server administration tasks," in the section titled "Managing server connections," under "Using Web Administration:", the description of the IP address is as follows:

Specifies the IP address of the client that has a to the server.

This sentence should be:

Specifies the IP address of the client that has a connection to the server.

Missing information about the idsicrt command:

The Description section of the idsicrt command should contain the following information:

Attention: When you create a new directory server instance, be aware of the information that follows. If you want to use replication, you must synchronize the encryption keys of the server instances to obtain the best performance.

If you are creating a directory server instance that must be cryptographically synchronized with an existing directory server instance, you must synchronize the encryption keys on the server instances before you do any of the following because the server will generate server encryption keys:

• Start the second server instance
• Run the idsbulkload command from the second server instance
• Run the idsldif2db command from the second server instance

See Appendix I, "Synchronizing two-way cryptography between server instances," on page 537 for information about synchronizing directory server instances.

Corrections to the idsdb2ldif command:
(Work item XX02361)

In the description of the options for the idsdb2ldif (or db2ldif) command, the description of the -t parameter requires changes:

• -t | <encryption salt> should be simply -t <encryption salt>

• The following sentences are incorrect and should be removed: "Use the ? to generate a password prompt. Using this prompt prevents your encryption salt from being visible through the ps command." There is no ? option for the -t parameter.

Corrections to the idsldapdiff command:
(Work item XX03031)

There are corrections to the idsldapdiff command. The corrected information is in the following file, and changes are marked with revision bars in the left column:


Notes about the idsgendirksf utility:
(Work items XX02352, XX02368)

1. The description for the idsgendirksf utility includes the following statement:

"The original salt value can be obtained by searching the server instance’s 'cn=crypto,cn=localhost' entry. The attribute value is
ibm-slapdCryptoSync."

This statement is incorrect. The attribute value for the original salt value is ibm-slapdCryptoSalt.

2. When using the idsgendirksf utility, if you use a character in the salt value or the encryption seed value that has special meaning to the command shell you are using, the character must be preceded by an escape character so that it will not be interpreted by the command shell. This is true even if the character is in the acceptable character range documented in the Administration Guide.

For example, on AIX, if you use the ` character when specifying the salt value (using the -s parameter), you must precede the ` character with the \ character.

3. On AIX, Linux, Solaris, and HP-UX systems only, after you run the idsgendirksf utility, the ownership of the ibmslapddir.ksf file is root:system. You must change the ownership of this file to directory_server_instance owner:instance_owner_group.

Corrections to the idslogmgmt utility:
(Work item XX03831)

All references to the file, "idslogmgmtinit.log", are incorrect. No such file exists.

Corrections to "Chapter 13. Replication":
(Work item XX02267)
(Work item XX02369, PMR 70848,499,000)

In "Chapter 13. Replication," there are corrections to the following sections:

• Key Stash File name is incorrect

All references to the file "ibmslapdconf.ksf" are incorrect and should read "ibmslapdcfg.ksf" instead.

• "Setting up a simple topology with peer replication"

There are corrections to the "Using Web Administration" section. The corrected procedure is attached:

There are corrections to the "Using the command line" section. The corrected procedure is attached:

• "Changing the replica to a forwarding server" (under "Creating a master-forwarder-replica topology")

There are corrections to the "Using the command line" section. The corrected procedure is attached:

• "Setting up a complex topology with peer replication"

There are corrections to the "Using the command line" section. The corrected procedure is attached:


Invalid idsbulkload parameter:
(Defect 92315)

In the description of the idsbulkload (or bulkload) command, a -D parameter is listed. This parameter is not valid. Use the -e parameter instead.

idsslapd, ibmslapd:

The current documentation incorrectly states that the -c option is to define the <adminsecureport> .

The -c option runs the server in console mode for UNIX systems. This option is not needed for Windows systems because the command, ibmslapd.cmd, always runs the directory server in console mode.

Correction to Appendix G. Password policy operational attributes:

In the "Password policy queries" section of Appendix G, the command in the following paragraph is incorrect:

To query for entries for which the password is about to expire, use the pwdChangedTime. For example, to find passwords which expire on August 26, 2004, with a password expiration policy of 186 days, query for entries for which the password was changed at least 186 days ago (February 22, 2004):

idsldapsearch –b "cn=users,o=ibm" –s sub
     "(!(pwdChangedTime>20040222000000Z))" <dn>

In the command, (pwdChangedTime>20040222000000Z) should be changed to (!(pwdChangedTime>=20040222000000Z).

The corrected command is:

idsldapsearch –b "cn=users,o=ibm" –s sub
     "(!(pwdChangedTime>=20040222000000Z))" <dn> 


Clarification to Appendix I. Synchronizing two-way cryptography between server instances:
(Work item XX02408, PMR 43998,370,000, APAR IO03347)

Appendix I in the Administration Guide is corrected as follows. (This is also Appendix E in the Installation and Configuration Guide.) The complete appendix is shown here.

Synchronizing two-way cryptography between server instances

If you want to use replication, use a distributed directory, or import and export LDIF data between server instances, you must cryptographically synchronize the server instances to obtain the best performance.

If you already have a server instance, and you have another server instance that you want to cryptographically synchronize with the first server instance, use the following procedure before you do any of the following:

• Start the second server instance
• Run the idsbulkload command from the second server instance
• Run the idsldif2db command from the second server instance

To cryptographically synchronize two server instances, assuming that you have already created the first server instance:

1. Create the second server instance, but do not start the server instance, run the idsbulkload command, or run the idsldif2db command on the second server instance.
2. Use the idsgendirksf utility on the second server instance to recreate the ibmslapddir.ksf file (the key stash file) from the first server instance. This file is used to replace the second server instance's original ibmslapddir.ksf file. For information about the idsgendirksf utility, see “idsgendirksf” in the IBM Tivoli Directory Server Version 6.0 Administration Guide. The file is in the idsslapd-instance_name\etc directory on Windows systems, or in the idsslapd-instance_name/etc directory on AIX, Linux, Solaris, and HP-UX systems. (instance_name is the name of the directory server instance)
3. Start the second server instance, run the idsbulkload command, or run the idsldif2db command on the second server instance.

The server instances are now cryptographically synchronized, and AES-encrypted data will load correctly.

Although the procedure discusses two server instances, you might need a group of server instances that are cryptographically synchronized.

Note: When importing LDIF data, if the LDIF import file is not cryptographically synchronized with the server instance that is importing the LDIF data, any AES-encrypted entries in the LDIF import file will not be imported.

Corrections to "Appendix N. Setting up SSL security – SSL scenarios":
(Work item XX02603, PMR 73973,033,000, APAR IO04029, Defect 92133)

In Appendix N, the following corrections should be made to the procedure in the section called "Creating secure connections between IBM WebSphere Application Server, and the IBM Tivoli Directory server and the administration daemon":

• The note at the beginning of step 2 should be removed. The note is as follows:

Note: The .jks file should not have the same name as the .kdb file if they are stored in the same directory.

• The following note should be added after the first bulleted item ("User-assigned label for the key pair...") in step 2g:

Note: Be sure that you do not use the same label that you used in step 1g.


• Problem Determination Guide

Incorrect log paths:
(Work item #XX02669, PMR #90633,999,000, APAR #IO04283)

In "Chapter 2. Logging utilities," the path given for the logs is incorrect. The path should be:

• top level drive:\idsslapd-ds_inst_name\logs for Windows systems
• ds_inst_owner_home/idsslapd-ds_inst_name/logs for AIX, Linux, Solaris, and HP-UX systems

• C-Client SDK Programming Reference:

Must free memory used by res:
(Work item #XX02244; PMR # 38596,999,000)

In "Chapter 3. API Categories," there is a correction to the LDAP_SEARCH API category.

In the Usage section for LDAP_SEARCH, the last sentence of the fifth paragraph
currently reads:

The results contained in res must be freed when no longer in use by calling ldap_msgfree().

This sentence should instead say:

The memory allocated for res must be freed when no longer in use, whether or not the operation was successful, by calling ldap_msgfree().

Clarification to Dynamic server trace extended operation section in Appendix F:

In Appendix F, in the section called "Dynamic server trace extended operation," the Note at the end of the Description should be changed to:

Notes:

1. This extended operation is always enabled.
2. Global administrative group members have authority to perform the Dynamic Server Trace Extended Operation when it is directed to the directory server. However, global administrative group members do not have this authority when they request the extended operation against the Administration Daemon.

• Server Plug-ins Reference:

Matching rule plug-ins not supported:
(Work item XX02309, Defect 92410)

Matching rule plug-ins are not supported. Therefore, the following changes should be made:

• The following sections in Appendix B should be removed.
• "Matching Rule Plug-ins"
• "Parameters for Matching Rule Plug-ins"
(See the updated version of Appendix B under "Unsupported parameters removed from Appendix B:")
• Ignore any other references to matching rule plug-ins.

Unsupported parameters removed from Appendix B:
(Work item XX02660, PMR 79385,49R,000)

"Appendix B. Parameter Reference" lists parameters and constants that are not supported; these parameters should be removed. The updated appendix is attached:

Audit plug-ins section changed:
(Work item XX02309, Defect 92410)

The "Audit plug-ins" section in "Chapter 4. Operation plug-ins" has been significantly changed. The new section is attached:

Correction to example in Appendix D. Plug-in examples:
(Work item XX02309, Defect 92410)

For corrections to the example in "Appendix D. Plug-in examples," as well as a new example, see the Technote entitled "Incorrect example in Server Plug-ins Reference."

• Performance Tuning Guide

Optimization:

See "DB2 tuning and commands" (Chapter 3 in the PDF version). Go to ″Optimization and organization (reorgchk and reorg),″ and then to "Optimization."

Successful database optimization requires restarting ibmslapd; if the performance improvements not observed after flushing package cache.

Existing Document says " After a message displays indicating the database was successfully optimized, you must restart the server for the changes to take effect."

The modified Document read as " After a message displays indicating the database was successfully optimized, you may need to restart the server if you do not see performance benefits after flushing the package cache.

See Technote 1263999: Regular DB2 maintenance required for maintaining the ITDS ldap server


DB2 RUNSTATS command:
(Work item 2848)

There is an error in the section that discusses the DB2 RUNSTATS command.

The last sentence in the section, discussing the DB2 RUNSTATS command, states "You can use ALL for all tables." This statement is not correct. If you use the ALL parameter, the following error occurs:

SQL0104N An unexpected token "ALL" was found following "TABLE". Expected tokens may include: "<valid-table-name>". SQLSTATE=42601

Database organization (reorgchk and reorg):

While performing reorgchk it is not always required to start and stop ibmslapd because ITDS caches prepared DB2 statements.

Existing Document says " Because LDAP caches prepared DB2 statements, you must stop and restart ibmslapd for DB2 changes to take effect.

The modified Document read as "We may or may not need to restart ITDS after performing a idsrunstats or db2 reorg. This depends on the SQL statement that have been cached by DB2 and ITDS. If you do not notice a performance benefit after running the above mentioned tools and flushing the package cache, you may need to restart ITDS to realize the benefits.

See Technote 1263999: Regular DB2 maintenance required for maintaining the ITDS ldap server

• Clarifications:

Subset of server management tasks displayed in Web Administration Tool:
(Work item 2212; PMR 45379,999,706)

In the Web Administration Tool, the server management tasks that are displayed in the Navigation area vary depending on your authority, the capabilities of the server you are logging on to, or both.

For example, for a z/OS server, even if you are logged on as an administrator, you will see only Schema management and Directory management.

Questions & Answers about the proxy server:
(Work item XX02370, APAR IO03886)

Question: Can the proxy server be used to split requests between the master servers so that some servers receive read requests and other servers receive write requests?

Answer: The proxy server splits requests based on whether they are read or write requests. The proxy server always does both of the following:

• Directs write requests to the first master it finds for a given subtree. (To avoid conflicts, it does not use the second master.)
• Load balances all read requests across all servers holding that subtree.

Question: Assume the following setup:
Peer to peer replication is set up with one replica server off each peer-master. The primary master goes down, so the proxy server directs requests to the second master.

When the primary master comes back up, does the proxy automatically switch requests back over to the primary master, does this require a manual step, or does it wait for the second master server to fail?

Answer: Currently, when a master server goes down, the proxy will not failback to the first server until the second server fails.

Question: What is the purpose of the proxy? Is it:

• Failover of split requests between read/write
or
• Partitioning of the directory?

Answer: The proxy can fulfill either of these requests. Originally, the proxy server was intended to solve the directory partitioning issue, especially across a flat namespace. However, all the features of the proxy are designed so that it can be used as an LDAP-aware load balancer as well.