nss-pam-ldapd: design documentation

This page describes the changes that were made to the nss_ldap package by PADL Software Pty Ltd..

problems with nss_ldap

The most important problems with the original design are:

• every executable (that does name lookups) on the system will load the LDAP libraries and open connections to the LDAP server
• NSS lookups done in the boot process (e.g. by udev) will cause the usual timeout mechanism to be invoked (some ugly workarounds are available)
• doing hostname lookups through LDAP will cause deadlocks because the LDAP libraries will need to do hostname lookups to find the LDAP server (it's a little more subtle than that)

Furthermore the original implementation has a lot of cross-platform compatibility code for both the NSS side and the LDAP side. This is in principle a good thing but makes the code very hard to maintain.
With nss-pam-ldapd the focus has been on getting it to work with glibc on Linux with OpenLDAP. Portability code can then be added later on where needed. Adding this should be simpler and will be done by introducing compatibility macros and functions as not to burden the normal code.

main design goals

Most of the problems of nss_ldap are solved by splitting the library in two parts: a daemon that connects to the LDAP server and does all the requests and a thin NSS connector that passes requests to the daemon through a socket.

Communication between the NSS part and the server part is done using a simple protocol. The protocol hides the complexity of transforming LDAP replies into useful data and transforming the data in a format that is suitable as NSS results.
The protocol is described in the nslcd.h file.

Using a local socket ensures that we can easily detect the availability of the server component. Using this, the server component can be started during system boot after the ldap server is reachable (i.e. when networking is available).

advantages of nss-pam-ldapd

Apart from fixing some of the problems that were mentioned earlier nss-pam-ldapd has a number of other advantages:

• easier debugging and logging
• reloading configuration can be simply forced by restarting the server
• the amount of locking that needs to be done can be greatly reduced improving performance
• no more code to detect fork()s, close()ing of file descriptors, etc
• no more symbol clashes when an application linked agains a different LDAP or SSL library
• the number of connections to the LDAP server is limited and more controlled
• simpler, more modular code
• improved documentation

Most of this is possible because, as an NSS module, we are running in someone else's space. Opening files and connections (especially if they are open for longer periods of time) requires complicated locking, signal masking, checking file descriptors, etc. The OpenLDAP library has not been designed to be used in such environments which make things very difficult for developers.

overview of changes

The nss_ldap source was refactored extenisvely removing a lot of compatibility code. The NSS part of the code has been mostly rewritten from scratch digging into glibc source for definitions of all functions (a little more documentation would be useful).

A number of features have also been removed. The most importent of these will be re-added in a later release or upon popular demand. See the README in the distribution for more details.

With the design change and removal of lot of complexity some refactoring was done which resulted in a significantly smaller code size. This makes the codebase much more maintainable.

The above numbers were generated using David A. Wheeler's 'SLOCCount' over the ANSI C source code and excluding the test code. Note however that these numbers are not directly comparable because in some releases some features were removed and nss-pam-ldapd has less compatibility code.

Other solutions

If nss-pam-ldapd is not the right solution for you, the follownig options are also available.

• The original nss_ldap package by PADL Software Pty Ltd. on which nss-pam-ldapd was based. That package is aguably better tested and has some features that are missing in nss-pam-ldapd. Note however that it suffers from the problems described above.
• An alternative soltion is to update /etc/passwd information with information from LDAP. nsscache is a Python solution for this. Note however that this means that changes to the LDAP database are not instantanious and it is questionable whether it scales well for very large installations. It also supports less NSS maps than either of nss-pam-ldapd or nss_ldap.
• Also, the people of OpenLDAP are working on a module in slapd to do the part that nslcd is doing now. See the openldap-devel mailing list and cvs tree for details.