LDAP configuration management and troubleshooting on AIX
User management is an important part of distributed computing environments. It provides the consistent authentication and authorization services necessary for universal access. For centralized security, many customers use the IBM Directory Server, a centralized security mechanism supported on AIX®. To achieve a foolproof IBM Directory Server configuration and ready it for use, you need a good understanding of Lightweight Directory Access Protocol (LDAP) concepts and configuration management.
This article provides an overview of LDAP and its architecture. It also discusses LDAP configuration and management on AIX. The article focuses on troubleshooting different types of problems while configuring the LDAP server and client. The suggestions in the troubleshooting section should be helpful to AIX administrators, technical support, and the development community.
LDAP overview and architecture
LDAP is an industry standard protocol for accessing directory servers. IBM Directory Server needs to be configured to support user authentication through LDAP with both the AIX specific schema and the RFC 2307 schema on AIX.
LDAP is optimized for reading, browsing, and for searching directories and specialized databases storing ordered information. Many computing environments are designed to make network resources available to users from any location, such as workstations, public workstations, and the Web. IBM Directory Server can be used for user management to achieve this objective.
Figure 1 shows an overview of an LDAP configuration.
Figure 1. LDAP configuration
LDAP is a standardized protocol and specialized database for storing ordered information. When users log in, the LDAP client sends a query to the LDAP server to get the user and group information from the centralized database. DB2® is a database used for storing the user and group information. The LDAP database stores and retrieves information based on a hierarchical structure of entries, each with its own distinguishing name, type, and attributes. The attributes (properties) define acceptable values for the entry. An LDAP database can store and maintain entries for many users.
An LDAP security load module was created in AIX Version 4.3. This load module provides user authentication and centralized user and group management functions through the IBM SecureWay® Directory. A user defined on an LDAP server can be configured to log in to an LDAP client even if that user is not defined locally. The AIX LDAP load module is fully integrated with the AIX operating system.
Configuration of IBM Directory Server
IBM Directory Server on AIX can be configured with either:
ldapcfgcommand line tool
- The graphical version of the ldapcfg tool, called
The following file sets are required to configure IBM Directory Server:
- Install the DB2 file set db2_09_01.rte.
- Install the following file sets:
The following file sets are required for configuring the LDAP client.
Note: 61 represents version of the file set. It will vary depending upon the version you are installing.
- The system should run in 64-bit kernel mode. Use the
bootinfo -Kcommand to determine the kernel mode.
- AIX requires 64-bit hardware. Use the
bootinfo -ycommand to determine the hardware.
- A minimum of 512MB RAM is required. (For better results, use 1GB or more.)
- IBM Directory Server requires 80MB of free space in the file system where the DB2 database is to be created.
- If you plan to use the InstallShield GUI to install, be sure that you have at least 100MB of free space in the /var directory and at least 400MB in the /tmp directory.
AIX provides the
mksecldap command to set up the IBM Directory
servers and clients to exploit the servers.
mksecldap command performs the following tasks for the new
- Creates the ldapdb2 default DB2 instance.
- Creates the ldapdb2 default DB2 database.
- Creates the AIX tree DN (suffix) under which AIX user and group is stored.
- Exports users and groups from security database files of the local host into the LDAP database.
- Sets LDAP server administrator DN and password.
- Optionally sets server to use Secure Sockets Layer (SSL) communication.
- Installs the /usr/ccs/lib/libsecldapaudit, an AIX audit plug-in for the LDAP server.
- Starts the LDAP server after all the above is done.
- Adds the LDAP server entry (slapd) to /etc/inittab for automatic restart after reboot.
mksecldap -s -a cn=admin -p passwd -S rfc2307aix
All setup information is stored in the /etc/ibmslapd.conf file.
Configuration of an AIX client system for the IBM Directory Server
The ldap.client file set contains the IBM Directory client libraries,
header files, and utilities. You can use the
command to configure the AIX client against the IBM Directory Server, as
mksecldap -c -h <LDAP Server name> -a cn=admin -p adminpwd -S rfc2307aix
You must have the IBM Directory Server administrator DN and password to
configure the AIX client. Once the AIX client is configured, the
secldapclntd daemon starts running. Once the AIX client is
configured against the IBM Directory Server, change the SYSTEM attribute
in /etc/security/user file to
LDAP OR compat or
compat or LDAP to authenticate users against the AIX client
The /usr/lib/security/methods.cfg file contains the load module definition.
mksecldap command adds the following stanza to enable the
LDAP load module during the client setup.
LDAP: program = /usr/lib/security/LDAP program_64 = /usr/lib/security/LDAP64
The /etc/security/ldap/ldap.cfg file on the client machine has
configuration information for the
secldapclntd client daemon.
This configuration file contains information about the IBM Directory
binddn, and password information. The file is
automatically updated by the
mksecldap command during AIX
auth_type attribute in the /etc/security/ldap/ldap.cfg
file specifies where the user needs to be authenticated. If the
auth_type attribute is
UNIX_AUTH, then the user
is authenticated at the client system. If it is
then the user is authenticated on IBM Directory Server.
Configuration of IBM Directory Server with SSL
The IBM Directory Server and client can be configured with SSL. This avoids the transfer of data in the clear-text format over the network. It encrypts the information and then sends it over the network. IBM Directory Server encrypts the user's password information, and then sends it over the network when SSL is configured.
The following file sets are required to enable the server and client encryption support:
For initial server setup, run the following command:
mksecldap -s -a cn=admin -p pwd -S rfc2307aix -k usr/ldap/etc/mykey.kdb -w keypwd
where mykey.kdb is the key database, and keypwd is the password to the key database.
For servers that are configured and running, run:
mksecldap -s -a cn=admin -p pwd -S rfc2307aix -n NONE -k /usr/ldap/etc/mykey.kdb -w keypwd
For initial client setup, run:
mksecldap -c -h <ldapserver name> -a cn=admin -p adminpwd -k /usr/ldap/key.kdb -w keypwd
Frequently used commands on the AIX LDAP client system are listed in Table 1 below.
Table 1. Frequently used commands
|/usr/sbin/start-secldapclntd||Starts the |
|/usr/sbin/stop-secldapclntd||Stops the |
|/usr/sbin/restart-secldapclntd||Stops the currently running |
|/usr/sbin/ls-secldapclntd||Lists the |
|/usr/sbin/flush-secldapclntd||Clears the cache of the |
|mkuser -R LDAP <username>||Creates users from the LDAP client.|
This section includes several typical problems, followed by suggested solutions.
Problem: LDAP server starts in configuration only mode...
The LDAP server starts in configuration only mode while restarting the LDAP server or doing LDAP server configuration returns the following error: "Failed to initialize be_config. Error encountered. Server starting in configuration only mode."
- Confirm whether the server started in configuration only mode by using
the following command, or look at /var/ldap/ibmslapd.log for this
# ldapsearch -h teak01.upt -b "" -s base objectclass=* | grep config ibm-slapdisconfigurationmode=TRUE
- Sometimes the DB2 license key was not registered properly. This is one
of the main reasons for this problem. The license key has to be
registered, as follows, to resolve this problem:
- Log in as a user with root authority.
- Register the DB2 product license key:
#/usr/opt/db2_08_01/adm /db2licm -a /usr/ldap/etc/ldap-custom-db2ese.lic #/usr/opt/db2_08_01/adm /db2licm -a /usr/ldap/etc/db2wsue.lic
- If the above step doesn't resolve the problem, clean up the LDAP server configuration and export LDAP_DBG=1 before doing the LDAP server configuration again. The /var/ldap/dbg.out, /var/ldap/dbg.log, and /var/ldap/ibmslapd.log files should have required diagnostic information to debug this problem further.
Problem: Cannot log in to the system with LDAP user...
Cannot log in to the system with LDAP user after successful Directory Server configuration.
Make sure there are no errors in the following areas, which can lead to a false impression about the existence of a particular LDAP user.
- During client configuration, using
mksecldap -u <userlist>specifies a comma-separated list of usernames or ALL to enable all users on the client. This means SYSTEM and registry attributes of the users is set to LDAP.
mksecldap -c -h monster -a cn=admin -p adminpwd -u user1,user2
-uflag ensures that
user2users can be used as LDAP users on the client machine, but this flag does not add any users in the LDAP server database. Login is successful for these users if they are added to LDAP using
mkuser -R LDAP <user name>or while doing server configuration, as follows:
mksecldap -s -a cn=admin -p adminpwd -S rfc2307aix
All the local users will be added to LDAP in this case. As
user2are local users, they will be automatically added into the LDAP database.
- Verify that Directory Server is up and running. The
ibmslapdprocesses should be running:
# ps -eaf |grep ibm ldap 278760 1 0 Jan 14 - 0:08 /usr/ldap//bin/ibmdiradm -l ldap 434392 1 2 Jan 14 - 339:44 ibmslapd -f/etc/ibmslapd.conf
- Verify whether the LDAP client is up and running. The
secldapclntdprocess should be running:
# ps -eaf |grep -i secldap root 393408 1 0 Jan 14 - 0:15 /usr/sbin/secldapclntd root 725062 692358 0 03:20:38 pts/0 0:00 grep -i secldap
- Verify whether that user exists on the server:
# lsuser -R LDAP usr_3112 usr_3112 id=3112 pgrp=gp_3112 groups=gp_3112,gp_3118,gp_3124 home=/tmp shell=/usr/bin/ksh login=true su=true rlogin=true daemon=true admin=false sugroups=ALL admgroups= tpath=nosak ttys=ALL expires=0 auth1=SYSTEM auth2=NONE umask=22 registry=LDAP SYSTEM=KRB5LDAP OR compat logintimes= loginretries=0 pwdwarntime=0 account_locked=false minage=0 maxage=0 maxexpired=-1 minalpha=0 minother=0 mindiff=0 maxrepeats=8 minlen=0 histexpire=0 histsize=0 pwdchecks= dictionlist= fsize=-1 cpu=-1 data=262144 stack=65536 core=2097151 rss=65536 nofiles=2000 roles=
- Verify the user's registry and SYSTEM attributes. Both of them should
be set to LDAP.
lsuser -a registry SYSTEM username
- Verify whether the LDAP stanza is added into
# grep -p LDAP /usr/lib/security/methods.cfg LDAP: program = /usr/lib/security/LDAP program_64 =/usr/lib/security/LDAP64
Problem: What is required to migrate all the AIX users as LDAP authenticated users?
What is required to migrate all the AIX users as LDAP authenticated users?
mksecldap allow a user to migrate a specific set of AIX
users while doing server configuration?
No. By default,
migrates all AIX users as LDAP authenticated users while doing server
If you do not want to migrate any AIX users as LDAP users, run the
mksecldap command with
#mksecldap -s -a cn=admin -p adminpwd -s rfc2307aix -u NONE
Problem: mkuser might return an error message
mkuser command might return the following error
# mkuser -R LDAP test 3004-686 Group "staff" does not exist. 3004-703 Check "/usr/lib/security/mkuser.default" file.
If the LDAP client and NIS client are configured on the same machine, then users are not able to create users from the AIX LDAP client. They get the above error message. You can rectify this problem by installing APAR IY90556.
Problem: Does mksecldap allow a user to migrate a specific set of AIX users?
mksecldap allow a user to migrate a specific set of AIX
users while doing server configuration?
mksecldap does not support
migrating a specific set of users as LDAP users while doing server
configuration. To handle this requirement, run the
command so that no AIX user is migrated, and create the required users
mkuser -R LDAP later.
It's important to note that the
-u flag, while doing server
configuration, only accepts NONE as an argument and any other argument is
mksecldap -s -a cn=admin -p adminpwd -S rfc2307aix -u user1,user2
All local users are exported in this case.
Problem: Client configuration problems if server configuration is done with -u NONE
This is broken down into three problems.
/usr/sbin/mksecldap -c -h batonrouge05.upt.austin.ibm.com -a cn=admin -p passw0rd
"Cannot find users from all base DN
client setup failed."
The client setup basically does the ldapsearch to see if there are any users added to the LDAP server already. The configuration fails if it does not find any users in LDAP. At least one user should be added to LDAP to overcome this problem.
The following ldif file should be added to LDAP DIT using the
dn: ou=People,cn=admin ou: People objectClass: organizationalUnit dn: uid=testuser,ou=People,cn=admin uid: testuser objectClass: aixauxaccount objectClass: shadowaccount objectClass: posixaccount objectClass: account objectClass: ibm-securityidentities objectclass: top cn: testuser passwordchar: * uidnumber: 203 gidnumber: 203 homedirectory: /home/testuser loginshell: /usr/bin/ksh isadministrator: false
mksecldap -c -h batonrouge05.upt.austin.ibm.com -a cn=admin -p passw0rd
"Cannot find the group base DN from the LDAP server.
Client setup failed."
The group base DN should be present in the LDAP DIT before configuring the client. The above failure is due to non-existence of a group base DN. A group needs to be added to resolve this problem.
The following ldif file should be added to the LDAP DIT using the
dn: ou=Groups,cn=admin ou: Groups objectClass: organizationalUnit dn: cn=testgrp,ou=Groups,cn=admin cn: testgrp objectclass: aixauxgroup objectclass: posixgroup objectclass: top gidnumber: 203 memberuid: testuser isadministrator: false
Creating a user with
mkuser when the server is
-u NONE and the client has been successfully
# mkuser -R LDAP id=1000 pgrp=grp_2000 groups="grp_2006,grp_2012" usr_1000 Group "staff" does not exist. Check "/usr/lib/security/mkuser.default" file.
mkuser command has a legacy behavior of checking the
defaults first, even if it is not going to use them. It fails, since a
group called staff does not exist.
All the problems in this section will be resolved in one shot if you add the following ldif file to LDAP.
dn: ou=Groups,cn=admin ou: Groups objectClass: organizationalUnit dn: cn=staff,ou=Groups,cn=admin cn: staff objectclass: aixauxgroup objectclass: posixgroup objectclass: top gidnumber: 203 memberuid: testuser isadministrator: false dn: ou=People,cn=admin ou: People objectClass: organizationalUnit dn: uid=testuser,ou=People,cn=admin uid: testuser objectClass: aixauxaccount objectClass: shadowaccount objectClass: posixaccount objectClass: account objectClass: ibm-securityidentities objectclass: top cn: testuser passwordchar: * uidnumber: 203 gidnumber: 203 homedirectory: /home/testuser loginshell: /usr/bin/ksh isadministrator: false
The ldif file can be added to the LDAP server, as follows:
#/usr/bin/ldapadd -D $ADMIN_DN -w $ADMIN_DN_PASSWD -f <ldif file>
The base DN of a configured LDAP server must be used in the ldif file. Otherwise, this ldif file cannot be successfully added.
- Understanding LDAP - Design and Implementation: This IBM Redbooks publication will help you create a foundation of LDAP skills, as well as install and configure the IBM Directory Server.
- IBM Tivoli® Directory Server Administration Guide: This guide contains the information that you need to administer the IBM Tivoli Directory Server.
- Read the following IBM Redbooks:
- Check out other articles and tutorials written by Uma Chandolu:
- AIX and UNIX®: The AIX and UNIX developerWorks zone provides a wealth of information relating to all aspects of AIX systems administration and expanding your UNIX skills.
- AIX 5L™ Wiki: A collaborative environment for technical information related to AIX.
- Search the AIX and UNIX library by topic:
- IBM trial software: Build your next development project with software for download directly from developerWorks.