Using Lightweight Directory Access Protocol with AIX 4.3.3


About this document
    Related documentation
Exploitation of the security subsystem
Setup of an LDAP security information server
Setup of an LDAP client
LDAP user management
Updated documentation
Common problems and solutions
    LDAP client daemon hangs
    DMT hangs while browsing the aixsecdb tree
    Older versions of mksecldap do not support LDAP 3.2
    Problem with directory replication
    Login hangs when all LDAP servers are down

About this document

This document provides information on setting up, using, and managing Lightweight Directory Access Protocol (LDAP). It also contains updated documentation that helps to understand how LDAP works, along with solutions to some common LDAP problems.

Related documentation

The product documentation library is also available:
http://www.rs6000.ibm.com/resource/aix_resource/Pubs/index.html


Exploitation of the security subsystem

LDAP defines a standard method for accessing and updating information in a directory (a database), either locally or remotely, in a client-server model. The LDAP method is exploited by a cluster of hosts to allow centralized security authentication, as well as access to user and group information. This functionality is intended to be used in a clustering environment to keep authentication, user, and group information common across the cluster.

The LDAP exploitation of the security subsystem is implemented as the LDAP authentication load module. It is conceptually similar to the other load modules, such as NIS, DCE, KRB5, etc. The load modules are defined in the /usr/lib/security/methods.cfg file. The implementation of the LDAP authentication load module is low level and is handled by the libraries. Once the LDAP authentication load module is enabled to serve user and group information, most high level API, commands, and system management tools should work in the same manner as in a normal environment. An -R flag is introduced for most high level commands to work through different load modules. For example, to create an LDAP user named joe from a client machine, enter:

	mkuser -R LDAP joe

The client system checks for whether a user is an LDAP user through user's SYSTEM attribute in the /etc/security/user file. If the user's SYSTEM is set to LDAP, that user can only authenticate through LDAP. If the SYSTEM attribute in the default stanza is set to LDAP, then all users who do not have a SYSTEM attribute set are considered LDAP users. The LDAP keyword can be used with other SYSTEM attribute values as described in Identification and Authentication for AIX documentation. The client side communicates to the server through the secldapclntd daemon. The daemon accepts requests from applications (through the library APIs), queries the LDAP server, and returns data to the application. The secldapclntd daemon is also responsible for caching.


Setup of an LDAP security information server

To set up a system as an LDAP security information server to serve authentication, user, and group information through LDAP, the LDAP server and client packages must be installed. The LDAP server needs to be configured as a client as well as a server. The DB2 database is also needed, as the LDAP server requires it. If the Secure Socket Layer (SSL) is required, the GSKit must be installed. The system administrator must create a key using the ikeyman utility. The certificate of the server key must be carried to the clients.

The command mksecldap can be used to set up an LDAP security information server. It sets up a database with the name ldapdb2, populates the database with the user and group information from the local host, and sets the LDAP server administrator DN (Distinguished Name) and password. It also optionally sets up SSL for client and server communication if you choose to do so. Next, mksecldap loads a server plugin (ibsecldap.a), and starts the LDAP server process (slapd). mksecldap also adds an entry in the /etc/inittab file, so that the LDAP server will be started at the next reboot. The entire LDAP server setup is accomplished through mksecldap, which updates the slapd.conf (SecureWay Directory Version 3.1), or slapd32.conf (SecureWay Directory Version 3.2). There is no need to accomplish configuration through the LDAP web management interface.

All the user and group information is stored under an AIX tree (suffix). The default suffix is cn=aixsecdb. mksecldap accepts a user supplied suffix through the -d option. If the user supplied suffix does not have cn=aixsecdb as its first RDN (Relative Distinguished Name), mksecldap prefixes the user supplied suffix with cn=aixsecdb. This AIX tree is ACL (Access Control List) protected. A client must bind to the LDAP server administrator to gain access to the AIX tree.

The mksecldap command works even if an LDAP server has been set up for other purposes, for example, Blue Pages information. In this case, mksecldap adds the AIX tree and populates it with the AIX security information to the existing database. This tree is ACL protected independently from other trees. The LDAP server works as it once did. In addition, it also serves as an AIX LDAP Security Server. It is strongly recommended that you back up your existing database before running mksecldap to set up the security server to share the same database.

After the LDAP security information server is successfully set up, the same host needs to be set up as a client.

If the LDAP security information server setup is not successful, you can undo the setup by running mksecldap with the -U flag. This restores the slapd.conf (or slapd32.conf), to its pre-setup state. Please run mksecldap with the undo option after an unsuccessful setup before trying to run mksecldap again. Otherwise, setup residuals may still be in this configuration file, which may cause failure of a subsequent setup. The undo option does not do anything to the database or its data. This is because the database could be a pre-existing database before mksecldap is run for the authentication server setup. The administrator has to remove the database manually if the database is created by mksecldap. For a pre-existing database, the administrator must make a decision on what steps to take to recover if mksecldap adds data to the database.

For more information on setting up a LDAP security information server, please refer to the mksecldap command section.


Setup of an LDAP client

The client must have the LDAP client package installed. If the SSL is required, the GSKit needs to be installed, key created, and the LDAP server SSL key certificate added to this key.

The mksecldap command can be used to set up the client. To have this client contact the LDAP security information server, the server name must be supplied during setup. The server's administrator DN and password are also needed for the client to access the AIX tree on the server. mksecldap saves the server administrator DN, password, server name, AIX tree DN on the server, and the SSL key path and key password to the /etc/security/ldap/ldap.cfg file.

Multiple servers can be supplied to the mksecldap during client setup. In this case, the client will contact the servers in the supplied order and establish connection to the server that it can first successfully bind to. If a bad connection occurs between the client and the server, a reconnection request is tried using the same logic. The AIX Security LDAP exploitation model does not support referral. It is important for the administrator to keep the replicating servers synchronized.

The client communicates to the LDAP security information server through a client side daemon (secldapclntd). If the LDAP load module is enabled on this client, high level commands eventually will communicate to this daemon through the library APIs. The daemon queries the server and returns the information back to the caller.

Other fine-tuning options can be supplied to the mksecldap during client setup. These options include setting the number of threads used by the daemon, the cache entry size, and the cache expiration timeout. These options are for advanced users only. Under most cases, the default values are sufficient.

A comma separated user list can be supplied to the mksecldap command during client setup. These users' SYSTEM attributes are set to LDAP. Once this is accomplished, these users can only authenticate through the LDAP load module. Note that mksecldap does not add these users to the LDAP security information server. This is to avoid duplicate user IDs in the LDAP database. It is recommended that the administrator use the mkuser command with the -R LDAP, flag to create these users on the LDAP server.

During the last steps of the client setup, mksecldap starts the client side daemon and adds an entry in the /etc/inittab file so that the daemon will be started at the next reboot. You can check to verify the setup by checking the secldapclntd process. If the process is running, the setup was successful (provided that the LDAP security information sever was set up and running).


LDAP user management

Management of users and groups on the LDAP security information server can be done on any LDAP client by using the AIX high level commands. An -R flag is provided for most of the high level commands to manage users and groups using LDAP, as well as other authentication load modules, such as DCE, NIS, and KRB5. For more information concerning the use of the -R flag, refer to each of the user and group's management commands.

To enable a user to authenticate through LDAP, run the chuser command to change the user's SYSTEM attribute value to LDAP. By setting the SYSTEM attribute value according the defined syntax, a user can be made to authenticate through more than one load module (for example, compat or LDAP.) For more information on setting users' authentication methods, please refer to Identification and Authentication and the SYSTEM attribute syntax defined in the /etc/security/user file in AIX documentation.

Two methods exist for creating an LDAP user at client setup by running mksecldap with the -u flag, and each is detailed below. The following information is important for the administrator to know when using the -u flag:

To enable all LDAP users to authenticate through LDAP on a local host, whether they are defined locally or not, modify the default stanza of the /etc/security/user file and include LDAP as its value. All users that do not have a value defined for their SYSTEM attribute will follow what is defined in the default stanza (for example, if the default stanza has SYSTEM = compat, changing it to SYSTEM = compat OR LDAP will allow authentication of these users either through AIX or LDAP). Changing it to SYSTEM = LDAP will enable these users to authenticate exclusively through LDAP. Users who have a SYSTEM attribute value defined are not affected by the default stanza.


Updated documentation

ldap.cfg file format

Purpose

secldapclntdserves as the LDAP client side daemon configuration file.

Description

The /etc/security/ldap/ldap.cfg file describes the LDAP Security Information Server configuration information needed for the client side daemon (secldapclntd), to authenticate to the server and to establish a connection.

The /etc/security/ldap/ldap.cfg file is created by running mksecldap to set up an LDAP client. The secldapclntd daemon reads this configuration file during its startup. The content of this configuration file can be changed by running mksecldap with the -c flag, together with the new configuration information.

The /etc/security/ldap/ldap.cfg file may contain the following fields:

ldapservers
Specifies a comma seperated LDAP Security Information Servers. These servers can either be the primary server and/or replica of the primary server.
ldapadmin
Specifies the administrator DN of the LDAP Security Information Server(s).
ldapadmpwd
Specifies the password of the administrator DN.
ldapaixdn
Specifies the AIX tree DN (suffix) of the AIX security information of the LDAP Security Information Server.
ldapsslkeyf
Specifies the SSL key file path.
ldapsslkeypwd
Specifies the SSL key password.

Example

The following is an example of a /etc/security/ldap/ldap.cfg file:

	ldapservers:<server1.ibm.com,server2.ibm.com>
	ldapadmin:cn=admin
	ldapadmpwd:rootpwd
	ldapaixdn:cn=aixsecdb

Related Information

mksecldap command

Purpose

Sets up an AIX cluster to use LDAP for security authentication and data management.

Syntax

To set up an LDAP security information server, enter the following:

mksecldap -s -a <adminDN> -p <adminpasswd> -d <AIXtreeDN> -k \
<sslkeypath> -w <sslkeypasswd> -U

To set up an LDAP client, enter the following:

mksecldap -c -a <adminDN> -p <adminpasswd> -h <serverlist> -d \
<AIXtreeDN> -u <userlist> | ALL -k <sslkeypath> -w <sslkeypasswd> \
-w <sslkeypasswd> -t <cachetimeout> -C <cachesize> -P <num-of-thread>

NOTE: This command can be run by root user only.

Description

The mksecldap command sets up an AIX cluster consisting of a server(s), and one or more clients to use LDAP for security authentication and data management. This command must be run on the server and all the clients.

NOTE: The server (-s flag) and the client (-c flag) options cannot be run at the same time. When setting up a server, the mksecldap command should be run twice on that machine - once to set up the server and again to set up the client.

For server setup (with the -s option), the mksecldap command:

NOTE: All the LDAP configuration will be saved into the slapd.conf (version 3.1), or slapd32.conf (version 3.2), LDAP server configuration file.

For client setup (with the -c option), the mksecldap command:

NOTE: The client configuration data is saved to the /etc/security/ldap/ldap.cfg file.

AIX user/group management commands can be used to accomplish LDAP user/group management by supplying an -R LDAP flag following the command. For details, refer to the AIX command documentation.

Flags

On the server side:

-s
Indicates that the command is being run to set up the server.
-a adminDN
Specifies the LDAP server administrator DN.
-p adminpasswd
Specifies the cleartext password for the adminDN.
-d AIXTreeDN
Specifies the suffix of the AIX subtree.
-k sslkeypath
Specifies the full path to the SSL key of the server.
-w sslkeypasswd
Specifies the password for the SSL key.
-U
Undo the previous server setup to the LDAP configuration file.

On the client side:

-c
Indicates the command is being run to setup the client.
-a adminDN
Specifies the administrator DN of the LDAP server. It must match the one used for the server setup.
-p adminpasswd
Specifies the cleartext password of the adminDN of the LDAP server. It must match the one used for the server setup.
-h serverlist
Specifies a comma separated list of hostnames (server and backup servers).
-d AIXTreeDN
Specifies the suffix of the AIX subtree of the LDAP server. It must match the one used for the server setup.
-u userlist | ALL
Specifies the comma separated list of usernames. ALL to enable all users on the client.
-k sslkeypath
Specifies the full path to the client SSL key.
-w sslkeypasswd
Specifies the password for the client SSL key.
-t cachetimeout
Specifies the maximum time length that a cache entry expires. The default is 300 seconds.
-C cachesize
Specifies the maximum number of user or group entries used in the client side daemon cache. The default is 1000 (1000 for user entries and 1000 for group entries.
-P num_of_thread
Specifies the number of threads the client side daemon uses. The default is 10, which is for advanced users to adjust the system performance.

Files Accessed:

              Mode                    File

	r       /etc/passwd
	r       /etc/group
	r       /etc/security/passwd
	r       /etc/security/limits
	r       /etc/security/user (on the server)
	rw      /etc/security/user (on the clients)
	r       /etc/security/environ
	r       /etc/security/user.roles
	r       /etc/security/lastlog
	r       /etc/security/smitacl.user
	r       /etc/security/mac_user
	r       /etc/security/group
	r       /etc/security/smitacl.group
	r       /etc/security/roles	
	rw      /etc/security/login.cfg (on the server)
	rw      /etc/slapd.conf (on the server)
	rw      /etc/aix.slapd.conf (on the server)

Examples:

secldapclntd daemon

Purpose

Provides and manages connection between the AIX LDAP load module of the local host and LDAP Security Information Server, and handles transactions from the LDAP load module to the LDAP Security Information Server.

Syntax

NOTE: The secldapclntd daemon is normally started by the init process.

	/usr/sbin/secldapclntd  -C <CacheSize> -p <NumOfThread> -t \
	<CacheTimeOut>

Description

The secldapclntd daemon accepts requests from the LDAP load module, forwards the request to the LDAP Security Information Server, and passes the result from the server back to the LDAP load module. This daemon reads the configuration information defined in the /etc/security/ldap/ldap.cfg file during its startup and authenticates to the LDAP Security Information Server using the server administrator's distinguished name and password and establishes a connection between the local host and the Server.

If multiple servers are specified in the /etc/security/ldap/ldap.cfg file, the secldapclntd daemon tries each one of the servers in the order listed in the file until a successful connnection is established. Once a connection is established, all communication will be carried out between the local host and that specific server. If an interupted connection occurs, (for example, a connecting server is down), during the lifetime of the daemon, the daemon automatically tries to reconnect to the server next on the list.

The secldapclntd daemon is a multi-threaded program. The default number of threads used by this daemon is 10. An administrator can fine-tune the system performance by adjusting the number of threads used by this daemon.

The secldapclntd daemon caches information retrieved from the LDAP Security Information Server for performance purposes. If requested information can be found in the cache and the information has not expired, the information will be returned to the requester. Otherwise, the secldapclntd daemon will make a request to the LDAP Security Information Server for the information. The default number of cache entries used by the daemon is 1000 entries. A cache entry expires in 300 seconds. Both the number of cache entries and the timeout value can be changed at the daemon startup time.

Flags

-C CacheSize
Sets the maximum cache entries used by the secldapclntd daemon to CacheSize number of entries. The default CacheSize is 1000.
-p NumOfThread
Sets the number of thread used by the secldapclntd daemon to NumOfThread threads. The default NumOfThread is 10.
-t CacheTimeout
Sets that the a cache expires in CacheTimeout seconds. The default CacheTimeout is 300.

Examples

The /etc/security/ldap/ldap.cfg file contains information needed by the secldapclntd daemon to connnect to the server.


Common problems and solutions

LDAP client daemon hangs

Problem

The AIX LDAP client daemon hangs after entering the following command:

	lsuser ALL

Solution

Once the daemon hangs, the authentication and authorization processes seems to hang too, which prevents user login. The APAR and PTF that solve this problem are IY11946 and U473907 for bos.rte.security 4.3.3.26, respectively.

DMT hangs while browsing the aixsecdb tree

Problem

DMT may hang when you attempt to browse the aixsecdb tree.

Solution

APAR IY11946 corrects this problem, however, it only corrects the DMT hang problem. You will still not be able to browse the AIX user and group part of the LDAP tree. This problem is currently being resolved. However, as a workaround, you can accomplish the following:

  1. Stop the LDAP server.
  2. Using your preferred editor, open the /etc/slapd32.conf file and comment out the following line by adding a # (pound sign) at the beginning of the line:
    ibm-slapdPlugin: preoperation /usr/ccs/lib/libsecldap.a(shr.o) \
    secldapInit
    
  3. Save the changes.
  4. Restart the LDAP server.

NOTE: Commenting out this plugin should be used only as a last resort and as a temporary workaround. We are working on a more permanent solution. In the future, additional functionality may be added to this plugin, so that commenting it out may no longer be an option.

Older versions of mksecldap do not support LDAP 3.2

Problem

The older versions of mksecldap do not support LDAP 3.2.

Solution

You must have the newer version of mksecldap, and use the new configuration file. It is now in LDIF format and referenced as /etc/slapd32.conf. The APAR that adds this support is IY12229, and the PTFs are U472948 for bos.rte.security 4.3.3.14 and U471346 for 4.3.3.25, respectively.

Problem with directory replication

Problem

When directory replication is performed, the entries you add may not be replicated from the master server to the replica server, which causes an insufficient access error.

Solution

You can work around this problem by commenting out the plugin in the /etc/slapd32.conf file by adding a # (pound sign), at the beginning of the following line:

ibm-slapdPlugin: preoperation /usr/ccs/lib/libsecldap.a(shr.o) \
secldapInit

With the mksecldap, this plugin is added which allows privileged port access.

NOTE: Commenting out this plugin should be used only as a last resort and as a temporary workaround. We are currently working on this problem. In the future, additional functionality may be added to this plugin, so that commenting it out may no longer be an option.

Login hangs when all LDAP servers are down

Problem

When all the LDAP servers are unavailable, the client will hang during login, not allowing even local users to login.

Solution

APAR IY14897 corrects this problem.


[ Doc Ref: 97785284825726     Publish Date: Feb. 09, 2001     4FAX Ref: 8802 ]