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.
The product documentation library is also available:
http://www.rs6000.ibm.com/resource/aix_resource/Pubs/index.html
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.
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.
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).
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:
mksecldap -c -u <user1,user2,...>
<user1,user2, ...> above represents a list of users. The users in this list can either be
locally defined users or remotely LDAP defined users. A SYSTEM = LDAP
entry is added to each of the user's stanza in the /etc/security/user file. These
users will only authenticate through LDAP. Enter the chuser command to modify the SYSTEM
attribute to allow authentication through multiple methods (for example, both local and LDAP).
Ensure that the users in the list exist on the LDAP security information server,
otherwise, they cannot log in from this host.
mksecldap -c -u ALL
The preceding command will add a SYSTEM = LDAP entry to the user stanza in the /etc/security/user file for all locally defined users. These users will only authenticate through LDAP. Also ensure that all of the locally defined users exist on the LDAP security information server, otherwise they can not log in from this host. A user that is defined on the LDAP server but not defined locally will not be able to log in from this host. To allow a remotely LDAP defined user to log in from this host, enter the chuser command with SYSTEM = LDAP entry for that particular user.
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.
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:
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:
On the client side:
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:
mksecldap -s -a cn=admin,o=ibm,c=us -p adminpwd
This sets up the server with administrator DN as cn=admin,o=ibm,c=us and the password as adminpwd. The AIX tree DN (suffix) is set to default: cn=aixsecdb.
mksecldap -s -a cn=admin,o=ibm,c=us -p adminpwd -d o=mycompany,c=us -k /usr/ldap/serverkey.kdb -w keypwd
This sets up the server using suffix cn=aixsecdb,o=mycompany,c=us (the mksecldap automatically converts the o=mycompany,c=us suffix to cn=aixsecdb,o=mycompany,c=us). It also sets the server to use the key stored at /usr/ldap/serverkey.kdb for SSL connection.
mksecldap -c -a cn=admin,o=ibm,c=us -p adminpwd -h server1.ibm.com,server2.ibm.com
This sets up the client to use server1.ibm.com and server2.ibm.com as its LDAP servers. The administrator DN and password of the server must be supplied for this client to authenticate to the server.
NOTE: The server must be set up to use the default AIX suffix in order for this to work, otherwise the explicit server AIX suffix must be supplied with the -d option for client setup.
mksecldap -c -a cn=admin,o=ibm,c=us -p adminpwd -h server1.ibm.com -d o=mycompany,c=us -k /usr/ldap/clientkey.kdb -w keypwd -u user1,user2,...
This sets up the client to use server1.ibm.com as its LDAP server, and tells the client that the AIX tree suffix is cn=aixsecdb,o=mycompany,c=us (mksecldap automatically converts the o=mycompany,c=us suffix to cn=aixsecdb,o=mycompany,c=us.) The suffix supplied with the -d option must match that used for the server setup. This also sets the client to use the key stored at /usr/ldap/clientkey.kdb for SSL connection. Users in the user1,user2,... list are set up to authenticate through LDAP.
mksecldap -c -u ALL
This sets all users on this local host to authenticate through LDAP.
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
Examples
/usr/sbin/secldapclntd
/usr/sbin/secldapclntd -p 20 -t 600
The /etc/security/ldap/ldap.cfg file contains information needed by the secldapclntd daemon to connnect to the server.
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:
ibm-slapdPlugin: preoperation /usr/ccs/lib/libsecldap.a(shr.o) \ secldapInit
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 ]