Configuring and troubleshooting ITDS 6.1 on AIX
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 Related topics 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.
# /opt/IBM/ldap/V6.0/bin/idsrmlink -i -l 64 -s fullsrv
Now create new links for 6.1 using the idslink utility. See idslink usage to understand flag descriptions.
# /opt/IBM/ldap/V6.1/bin/idslink -i -l 64 -s fullsrv
The following table shows the versions of AIX on which IBM Tivoli Directory Server 6.1 is supported.
AIX on pSeries (64-bit/32-bit)
|Operating system version||64-bit Directory Server components||32-bit Directory Server components|
|AIX 5.2 (ML5 or higher level for client or server)||Client, Server, Web Administration Tool||Client (operating system utility installation only)|
|AIX 5.3 (TL1 or higher level for client or server)||Client, Server, Web Administration Tool||Client (operating system utility installation only)|
|AIX 6.1 GA||Client, Server, Web Administration Tool||Client (operating system utility installation only)|
- 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).
- GSKit 22.214.171.124 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 126.96.36.199 or later fileset is required for GSKit.
- Embedded WebSphere® Application Server 188.8.131.52 for GUI Web Administration Tool.
- 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).
- For a server, be sure that asynchronous I/O is turned on. To turn on asynchronous I/O, do the following steps:
# /usr/sbin/chdev -l aio0 -P # /usr/sbin/chdev -l aio0 -P -a autoconfig=available
Tip: To install above-mentioned filesets, either use interactive "smitty installp" OR
#installp -acgvXYd "fileset location" "fileset list"
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.
# mksecldap -s -a cn=admin -p adminpasswd -S rfc2307aix -d o=ibm
# mksecldap -s -a cn=admin -p adminpasswd -S rfc2307aix -d o=ibm -u NONE \ -k [ssl key_db file] -w [ssl key passwd]
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.
# ps -eaf |grep ibm ldapdb2 307360 1 0 May 08 - 0:16 /opt/IBM/ldap/V6.0/sbin/64/ibmdiradm -I ldapdb2 ldapdb2 782344 1 5 01:50:46 pts/0 4:45 /opt/IBM/ldap/V6.0/sbin/64/ibmslapd -n \ -I ldapdb2 -f /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf
mksecldap has the limitation of creating only one default directory server and database instance. To configure more than one instance, see Configuring multiple instances of ITDS 6.1 on AIX.
Configuring multiple instances of ITDS 6.1 on AIX
ITDS 6.0 was introduced with a new phenomenon of directory server instance that lies above the database instance. There was no directory instance in prior versions of ITDS 6.0. So, only one default DB2 instance configured to one DB2 database. From 6.0 onwards, it is possible to have 'n' number of directory server instances configured to 'n' number of DB2 instances or DB2 databases.
Figure 1. Configuring server authentication
By looking into the figure, let's start the configuration process.
- Creating a directory server instance ID
This can be an existing user ID or a new user ID. The user ID must meet the following requirements:
- Be 8 characters or less.
- Have their primary group set to idsldap.
- Have their home directory.
- Have a valid, working password.
- Root user must be a member of the user's primary group (idsldap).
# mkuser pgrp=idsldap groups=staff home=/home/tam shell=/usr/bin/ksh tam
Make this new user password valid and ready for login
# passwd tam ...and set the password (to passw0rd) # telnet 'hostname' ...change the password when asked (to passw0rd)
Alternatively, the idsadduser command creates the DB2 and directory server instance owner and group at one shot.
# idsadduser -l "home_dir" -g "group_name" -u "user_name" -w "user_passwd" -n
- Use the idsicrt command to create the directory server instance.
# idsicrt -I tam -e tamencryption -n
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.
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.
Now list the available instances on the machine and confirm your instance existence.
# idsilist Directory server instances: ldapdb2 tam
Set the administrator DN and password for the created directory instance.
# idsdnpw -I tam -u cn=tam -p tam -n You have chosen to perform the following actions: GLPDPW004I The directory server administrator DN will be set. GLPDPW005I The directory server administrator password will be set. GLPDPW009I Setting the directory server administrator DN. GLPDPW010I Directory server administrator DN was set. GLPDPW006I Setting the directory server administrator password. GLPDPW007I Directory server administrator password was set.
- Configure the database for a directory instance.
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).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 (
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.
# /usr/bin/idscfgdb -I tam -t tam -l /home/tam -a tam -w passw0rd GLPCDB023I Database 'tam' will be configured. GLPCDB024I Database 'tam' will be created at '/home/tam' Do you want to.... (1) Continue with the above actions, or (2) Exit without making any changes:1 GLPCDB035I Adding database 'tam' to directory server instance: 'tam'. GLPCTL017I Cataloging database instance node: 'tam'. GLPCTL018I Cataloged database instance node: 'tam'. GLPCTL008I Starting database manager for database instance: 'tam'. GLPCTL009I Started database manager for database instance: 'tam'. GLPCTL026I Creating database: 'tam'. GLPCTL027I Created database: 'tam'. GLPCTL034I Updating the database: 'tam' GLPCTL035I Updated the database: 'tam' GLPCTL020I Updating the database manager: 'tam'. GLPCTL021I Updated the database manager: 'tam'. GLPCTL023I Enabling multi-page file allocation: 'tam' GLPCTL024I Enabled multi-page file allocation: 'tam' GLPCDB005I Configuring database 'tam' for directory server instance: 'tam'. GLPCDB006I Configured database 'tam' for directory server instance: 'tam'. GLPCTL037I Adding local loop back to database: 'tam'. GLPCTL038I Added local loop back to database: 'tam'. GLPCTL011I Stopping database manager for the database instance: 'tam'. GLPCTL012I Stopped database manager for the database instance: 'tam'. GLPCTL008I Starting database manager for database instance: 'tam'. GLPCTL009I Started database manager for database instance: 'tam'. GLPCDB003I Added database 'tam' to directory server instance: 'tam'.
Now, start the directory server for your instance and make sure it starts properly without any errors.
# ibmslapd -n -I tam -f /home/tam/idsslapd-tam/etc/ibmslapd.conf
You can cross-check by running ps -fu and make sure both ibmslapd and ibmdiradm processes are running for the 'tam' instance.
# ps -fu tam | grep ibm tam 671768 1 0 02:31:18 pts/0 0:00 /opt/IBM/ldap/V6.1/sbin/64/ibmdiradm -I tam tam 1695814 1 0 02:43:01 pts/0 0:00 /opt/IBM/ldap/V6.1/sbin/64/ibmslapd -n -I tam\ -f /home/tam/idsslapd-tam/etc/ibmslapd.conf
Also, be alert to check that the server does not start in configuration mode only!
# idsldapsearch -D cn=tam -w tam -p 1389 -s base -b "" objectclass=* \ | grep ibm-slapdisconfigurationmode ibm-slapdisconfigurationmode=FALSE
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.
So now the machine is ready with multiple directory server instances.
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.
Open this file and observe the default values for port numbers and other parameters.
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.
# ibmslapd -k -I tam # idscfgsuf -I tam -s "o=ibm" -n
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 Downloadable resources) to your Window's box and FTP it to your UNIX machines. Now, add this information to server in the following sequence.
# ibmslapd -n -I tam # idsldapadd -D cn=tam -w tam -p "port num" -v -f ldif_file.ldif # idsldapadd -D cn=tam -w tam -p "port num" -v âf add.containers.ldif # idsldapadd -D cn=tam -w tam -p "port num" -v âf add.aixid.ldif
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.
To learn the port number, type
idsilist -aand check for Port: under the 'tam' instance stanza.
To configure the LDAP client against the 'tam' server instance, use the port number as a unique parameter.
# mksecldap -c -h "ldap server" -a cn=tam -p tam -d o=ibm -n 1389
Unconfiguring the ITDS instance
- Undo the previous setup to the server configuration file:
# mksecldap -s -U
- Do a graceful shutdown of the ibmslapd and ibmdiradm processes:
# /opt/IBM/ldap/V6.1/bin/ibmdirctl -D cn=tam -w tam -p "admin port number" admstop Admin daemon is stopped # /opt/IBM/ldap/V6.1/bin/ibmdirctl -D cn=tam -w tam -p "port num" stop ibmslapd server is stopped.
- Drop the directory server instance:
# idsidrop -I tam -n # echo $? 0
- Stop the DB2 instance corresponding to the 'tam' instance.
Run as an instance owner:
# su - tam $ whoami tam $ /home/tam/sqllib/adm/db2stop 02/06/2008 03:50:13 0 0 SQL1064N DB2STOP processing was successful. SQL1064N DB2STOP processing was successful. $ exit
- Now drop the DB2 instance:
# /usr/opt/db2_09_01/db2/instance/db2idrop tam # DBI1070I Program db2idrop completed successfully
- Remove the instance owner and home. Finally, clean out the library space:
# rmuser tam # rm -rf /home/tam/ # slibclean
- 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.
- Problems seen while configuring database for a directory instance:
GLPCTL008I Starting database manager for database instance: 'ldapdb2'. GLPCTL010E Failed to start database manager for database instance: 'ldapdb2'. GLPCTL049I Adding TCP/IP services to database instance: 'ldapdb2'. . . GLPCTL008I Starting database manager for database instance: 'ldapdb2'. GLPCTL010E Failed to start database manager for database instance: 'ldapdb2'. GLPCTL026I Creating database: 'ldapdb2'. GLPCTL028E Failed to create database: 'ldapdb2'. The failure might have occurred because the system was not set up correctly before using the tool. GLPCTL011I Stopping database manager for the database instance: 'ldapdb2'. GLPCTL012I Stopped database manager for the database instance: 'ldapdb2'. GLPCDB004E Failed to add database 'ldapdb2' to directory server instance: 'ldapdb2'. GLPCDB026W The program did not complete successfully. View earlier error messages for information about the exact error. Server setup failed.
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:
# /usr/opt/db2_09_01/db2/instance/db2ilist ldapdb2
If a DB2 instance is present, drop it first using db2idrop (See the section above for more details.).
/usr/opt/db2_09_01/db2/instance/db2icrt -d -a SERVER -s ese -u ldapdb2 ldapdb2
(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
If the log has the following error:
SQL6031N Error in the db2nodes.cfg file at line number "1". Reason code "10". Update DBM cfg SYSADM_GROUP errcode = 8 >>>>>Error message = SQL6031N Error in the db2nodes.cfg file at line number "1". Reason code "10". <<<<< DBI1703E No valid service name or port number found.
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:
AIX Version 5 (C) Copyrights by IBM and by others 1982, 2007. login: u100 u100's Password: [LDAP]: 3004-610 You are required to change your password. Please choose a new one. u100's New password: Enter the new password again: 3004-010 Failed setting terminal ownership and mode. Connection closed.
This error message may indicate a broken or missing group file. The primary group is missing for user u100!".
# lsuser -R LDAP -a pgrp u100
So add this user as a member of group staff:
# chuser -R LDAP pgrp=staff u100 # lsuser -R LDAP -a pgrp u100 u100 pgrp=system
Retry logging in.
Directory server instance creation fails.
# idsicrt -I ldapdb2 -e myencryption GLPICR123E Unable to determine the ownership and permissions on the\ directory '/home/ldapdb2'. GLPICR024W The program did not complete successfully. View earlier \ error messages for information on the exact error.
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:
# ls -ld /home/ldapdb2/ drwxrwxr-x 2 211 dbsysadm 256 Jun 21 04:06 /home/ldapdb2/
User '211' owns /home/ldapdb2. Change the ownership to ldapdb2 user and rerun idsicrt:
# chown ldapdb2 /home/ldapdb2/ # ls -ld /home/ldapdb2/ drwxrwxr-x 2 ldapdb2 dbsysadm 256 Jun 21 04:06 /home/ldapdb2/
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:
# restart-secldapclntd //OR # mksecldap -c -h [ldap server] -a bindDN -p bindPassword -d baseDN -t 0
The following error occurs when instance owner 'ldapdb2' tries to start the ibmslapd process:
# 02/08/08 08:41:13 GLPCOM027E Attempt to bind failed with errno 13 \ (The file access permissions do not allow the specified action.). 02/08/08 08:41:13 GLPCOM006E SocketInit failed for port 389. 02/08/08 08:41:13 GLPSRV004I Terminating server.
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?
- Stop the ibmslapd process.
- Change ibm-slapdPort: [new non:ssl port] inside /home/ldapdb2/idsslapd-ldapdb2/etc/ibmslapd.conf under "dn: cn=Configuration" stanza.
- 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.
# idssetport -I [instance_name] -p [non:ssl port] -s [ssl port] -n
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 Related topics).
- For a list of all server and client utilities, see the Tivoli Directory Server, Version 6.1 Command line utilities
- The ITDS 6.1 Installation and Configuration Guide describes how to install, configure, and uninstall IBM Tivoli Directory Server version 6.1.
- SSL configuration for IBM Tivoli Directory Server 6.0 (Chethan Jain, developerWorks, February 2008) provides an overview of SSL configuration for the IBM Tivoli Directory Server 6.0 on the AIX 5L operating system.
- LDAP5.2 configuration management and troubleshooting on AIX (Uma Chandolu and Ravi K. Kovvila, developerWorks, May 2007) is a quick reference for IBM Directory Server configuration management on AIX.
- Read an article on developerWorks regarding DB2 problem determination.