Configuring and troubleshooting Tivoli Directory Server 6.1 on AIX

Introduction

IBM Tivoli Directory Server (ITDS) is the IBM implementation of the Lightweight Directory Access Protocol (LDAP) for supported Windows®, AIX®, System x™, System z™, System i™, System p™, Linux®, Solaris®, and HP-UX® operating systems. It is a powerful LDAP infrastructure that provides a foundation for deploying comprehensive identity management applications and advanced software architectures. It provides a server that stores directory information using a DB2® database, a proxy server for routing LDAP operations to other servers, a client, and a graphical user interface (GUI) for managing servers.

Several authentication methods are available with IBM Tivoli Directory Server, beyond basic usernames and passwords. ITDS supports digital certificate-based authentication, Access Control Lists, Challenge-Response Authentication Mechanism MD5 (CRAM-MD5) password encryption, the Simple Authentication and Security Layer (SASL), and Kerberos authentication.

ITDS is a beautified release compared to LDAP5.2. Some important features are:

• Multiple directory servers on a single computer:

  • Beginning with the 6.0 release, multiple directory server instances can coexist on the same computer. It also includes multi-homed support for directory servers.

• Security enhancements:

  • Replication agreements are more secure.

  • Password policy support is provided for directory administrator passwords.

  • Change log data and replication change data is more secure.

• Performance enhancements:

  • Enhancements to the bulkload utility reduce the time it takes to load LDAP entries into DB2 using the utility.

  • Search processing modifications have been made to improve the performance of base-scoped searches.

• Multiple versions of server and clients on a single computer:

  • A server from a previous release (6.0) can run on the same computer as a version 6.1 server.

  • A client from a previous release (4.1, 5.1, 5.2, or 6.0) can run on the same computer as a version 6.1 server.

  • The version 6.1 client can run on the same computer as version 4.1, 5.1, 5.2, or 6.0 servers.

Server and client utilities

The IBM Tivoli Directory Server SDK kit includes several command line utilities for manipulating the Directory Server and Database. For a list of all server and client utilities, see the Resources section. Although the article explains the required ones, you can tap them for easy administration.

Starting from version 6.1, system links are not created for LDAP client and server commands. Use the idslink utility to set the links to command-line utilities such as idsldapmodify and idsldapadd, and libraries such as libibmldap. For example, if a machine is installed with both 6.0 and 6.1 client-server filesets, default system links will be generated for all 6.0 client-server command line utilities. How do you create the links for version 6.1 by removing 6.0?

Use the idsrmlink command-line utility to remove links to the client and server utilities that were set by the 6.0 idslink command.

Now create new links for 6.1 using the idslink utility. See idslink usage to understand flag descriptions.

Software requirements

Required prerequisites:

• ITDS filesets.

• Universal Database Enterprise Server Edition (ESE). DB2 V9.1 ESE Fix Pack 2 OR Universal Database Enterprise Server Edition DB2 V8.1

• The Korn shell is required.

• Verify AIX is having 64-bit kernel (bootinfo -K).

Optional prerequisites:

• GSKit 7.0.3.30 is required for Secure Socket Layer (SSL) connection. To use GSKit, the IBM JDK 1.5 or an equivalent JDK is required.

• The xlC.aix50rte 6.0.0.0 or later fileset is required for GSKit.

• Embedded WebSphere® Application Server 6.1.0.7 for GUI Web Administration Tool.

Hardware requirements

• Verify AIX hardware is 64 bit. (bootinfo -y)

• For clients, a minimum of 128 MB RAM is required. For better results, use 256 MB or more.

• For servers, a minimum of 512 MB for each directory server instance, 256 MB for each database instance, and 1 GB for running the Web Administration Tool and Embedded WebSphere Application Server.

• Use at least 2 GB of disk space for a full server (including the client, the server, and the database).

Other:

• For a server, be sure that asynchronous I/O is turned on. To turn on asynchronous I/O, do the following steps:

Tip: To install above-mentioned filesets, either use interactive "smitty installp" OR

Configuring ITDS 6.1 using AIX utilities

mksecldap is the AIX wrapper script for configuring ITDS 6.1. AIX ships the mksecldap command under the bos.rte.security component for LDAP client-server configuration. ldapdb2 is the default directory server instance and DB2 instance that gets created upon the execution of mksecldap. Use "smitty ldap" for interactive configuration.

For non-SSL

For SSL

For overall SSL configuration, please refer to SSL configuration for ITDS 6.0.

On successful completion, ITDS 6.1 starts running with the ldapdb2 instance listening at non-secure port 389.

• • 1. Make this new user password valid and ready for login

• • 1. Alternatively, the idsadduser command creates the DB2 and directory server instance owner and group at one shot.

1. Use the idsicrt command to create the directory server instance.

• • 1. The default port number of 389 will be chosen for the first instance. For the second and third instance creation, 1389 and 2389 will be chosen. The system automatically chooses the rest of the port numbers.

    2. The database instance name is also the DB2 instance owner ID. It is recommended that you omit this option and let the system choose the directory server instance owner's name as the DB2 instance name.

    3. Now list the available instances on the machine and confirm your instance existence.

• • 1. Set the administrator DN and password for the created directory instance.

1. Configure the database for a directory instance.

   1. DB2 instance is the actual database where data gets stored, which in turn is associated with the directory server instance. When you configure the database, information about the database is added to the ITDS configuration file (ibmslapd.conf).

   2. Before configuring,

      • Stop the directory server. If this is the initial configuration, the server should not be running . However, you can verify this by running ps -eaf and making sure ibmslapd is not running.

      • Unset DB2COMM (unset DB2COMM).

• • 1. Now run idscfgdb to configure the database for a directory instance. Make sure the instance owner 'tam' has the rwx permissions for the /home/tam directory.

• • 1. Now, start the directory server for your instance and make sure it starts properly without any errors.

• • 1. You can cross-check by running ps -fu and make sure both ibmslapd and ibmdiradm processes are running for the 'tam' instance.

• • 1. Also, be alert to check that the server does not start in configuration mode only!

• • 1. If ibm-slapdisconfigurationmode is TRUE, correct the problem before proceeding. Look into /home/tam/idsslapd-tam/logs/ for logs and fix it. In case you were unable to correct it, unconfigure this instance and start from the beginning.

    2. So now the machine is ready with multiple directory server instances.

    3. The configuration file, ibmslapd.conf, for respective instances are located at /home/"instance name"/idsslapd-"instance name"/etc/ibmslapd.conf, for instance, /home/tam/idsslapd-tam/etc/ibmslapd.conf, for the 'tam' instance.

    4. Open this file and observe the default values for port numbers and other parameters.

    5. To maintain 'tam' instance user and group information, add a high-level suffix. Ensure that the directory instance server is stopped before you attempt it.

• • 1. Adding a new suffix does not actually create the corresponding LDAP object in the directory. You need to create an LDIF file and add this to server. Download the zip file (see Downloads) to your Window's box and FTP it to your UNIX machines. Now, add this information to server in the following sequence.

• • 1. add.container LDIF creates "Groups" and "People" repositories under o=ibm tree. add.aixid LDIF creates some standard AIX ID's and the default "Staff" group. The "People" branch represents a set of users from u0 to uN, where N can be any arbitrary integer. The "Groups" branch represents the set of groups from grp1000 to grpN, where N can be any arbitrary integer. The "System" branch is used to store miscellaneous, but essential, authentication entry information. Please note that mksecldap fails for client configuration if it does not find the default 'staff' group.

    2. To learn the port number, type idsilist -a and check for Port: under the 'tam' instance stanza.

    3. To configure the LDAP client against the 'tam' server instance, use the port number as a unique parameter.

Unconfiguring the ITDS instance

1. Undo the previous setup to the server configuration file:

1. Do a graceful shutdown of the ibmslapd and ibmdiradm processes:

1. Drop the directory server instance:

1. Stop the DB2 instance corresponding to the 'tam' instance. Run as an instance owner:

1. Now drop the DB2 instance:

1. Remove the instance owner and home. Finally, clean out the library space:

Problem determination

• To troubleshoot installation problems and perform recovery actions, refer to the Tivoli Directory Server Troubleshooting installation and uninstallation guide.

• For known limitations and general troubleshooting, see the Tivoli Directory Server Known limitations and general troubleshooting guide.

Miscellaneous problems

• Problems seen while configuring database for a directory instance:

• • • The reason for these problems are various and a couple of DB2 errors arose in a similar way. The first thing to try whenever you receive such a error is to create a DB2 instance explicitly. Check if there are any instances before you attempt it:

• • • If a DB2 instance is present, drop it first using db2idrop (See the section above for more details.).

• • • (If the instance is created successfully, please drop it back again using db2idrop and it is recommended that the ITDS tools create the instances for you.)

    • Does this command fail? Then, certainly it is a DB2 issue!

    • Look into directory server instance's DB2 logs for additional errors or wanings that might have been generated. The logs are located under /tmp/db2icrt.log.* and /home/ldapdb2/sqllib/db2dump/db2diag.log.

    • If the log has the following error:

• • • then this message usually has an issue with the hostname. The db2icrt script calls the db2iutil script, which issues the command /usr/bin/uname -n to get the host name, which is used for the db2nodes.cfg. Run "/usr/bin/uname -n" and check if the host name is correct for the system. If the hostname appears to correct, run nslookup. This should bring up the IP address of the nslookup server and then prompt for user input. At this point, enter the hostname returned by the uname command and confirm if this successfully returns an IP address for this hostname. If either of these commands fail, contact your system or network administrator to ensure that the machine is correctly configured. Adding an host entry inside '/etc/hosts' with proper IP address should resolve this problem.

• • A LDAP user trying to log in to the client machine encounters the following error:

• • • This error message may indicate a broken or missing group file. The primary group is missing for user u100!".

• • • So add this user as a member of group staff:

• • • Retry logging in.

• • Directory server instance creation fails.

• • • This error could be a result of improper server unconfiguration or the directory /home/ldapdb2 could be already owned by some other user and idsicrt is trying to create an ldapdb2 instance at this path. Check the directory permissions:

• • • User '211' owns /home/ldapdb2. Change the ownership to ldapdb2 user and rerun idsicrt:

• • You configured two LDAP clients on two different machines against a directory server. Assume client1 changes the password for a preexisting user 'u100'. User 'u100' tries to log in using client2 now. Login fails. Why?

    • The reason is the password changed on client1 is not yet reflected on client2. Either restart the secldapclntd daemon on client2 or make sure to set the cacheTimeout value to 0 during client configuration:

• • The following error occurs when instance owner 'ldapdb2' tries to start the ibmslapd process:

• • • The ibmslapd process is listening on privileged port (port 389). For the server to be able to use a privileged port (a port less than 1024), it must start as root to have permission to bind() to that port. After the bind(), it can step down (using setuid()) to run as the instance user. So, either change the port number to > 1024 and start it, or start the instance as a root user.

• • How do you bind the 'ibmslapd' process to a port number other than 389 for the ldapdb2 instance?

    1. Stop the ibmslapd process.

    2. Change ibm-slapdPort: [new non:ssl port] inside /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf under "dn: cn=Configuration" stanza.

    3. Restart the server.

• • • Similarly for SSL connection, change the below value under "dn: cn=SSL, cn=Configuration" stanza.

    • ibm-slapdSecurePort: [new ssl port]

    • 'idssetport' command substitutes the above procedure.

Conclusion

After reading this article, readers should have a better understanding of ITDS. Since the article does not explain all ITDS command line utilities, readers are advised to learn them from the Tivoli Information Center. Also, common troubleshooting tips are mentioned here. If you face new problems or have any solutions to problems, please visit the AIX technical/developer forum (See Resources).