Design documentation
This page describes the basic design of nss-pam-ldapd. It was started as a fork of nss_ldap to fix a number of shortcomings. The most important problems were:
- every executable (that does name lookups) on the system will load the LDAP libraries (and dependencies) and opens a connection to the LDAP server
- NSS lookups done during boot will slow down the system if the LDAP server is not yet available
- hostname lookups through LDAP can cause deadlocks because the LDAP libraries will need to do (reverse) hostname lookups for connecting to the LDAP server
Furthermore the original implementation had a lot of cross-platform
compatibility code throughout the code and a lot of complex constructs
to work as an NSS module. This made it hard to maintain.
With nss-pam-ldapd the initial focus has been on getting it to
work with glibc on Linux with OpenLDAP.
Portability code was added later for most of the platfoms that
nss_ldap supported in a way to not have the compatibility burden
the normal code.
Design
Most of the problems of nss_ldap were solved by splitting the functionality 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.
Later on a PAM module was added that also communicates with the daemon.
Communication between the NSS part and the server part is done using a
simple request/response protocol.
The protocol hides the complexity of transforming NSS and PAM queries
into LDAP operations and transforming LDAP replies into a format that is
suitable as NSS results.
The protocol is described in the nslcd.h file.
Using a local socket ensures that the availability of the server component can be easily tested. 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 the configuration can simply be forced by restarting the daemon
- a lot less locking and complexity in the code is required so we have better performance
- no more symbol clashes or other side-effects when an application is using a different LDAP or SSL library
- it is possible to secure the credentials needed to connect to the LDAP server
- the number of connections to the LDAP server can be controlled
- simpler, more modular code
- improved documentation
Since an NSS module (and PAM module to a lesser extent) is loaded into someone else's address space, opening files and connections (especially if they are open for longer periods of time) requires complicated locking, signal masking, checking file descriptors, special fork() handling, etc. The OpenLDAP library and most SSL libraries have not been designed to be used in such environments which make things very difficult. All this complexity is eliminated in nss-pam-ldapd.
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).
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.
Over the years features and support for other operating systems has been added. The 0.7 release added a PAM module and the 0.8 release included a Solaris NSS module. The 0.9 release included a switch in coding style and a good deal of new functionality (nested groups, password policy support, user modification functionality and more).
| release | NSS | PAM | nslcd | SLOC | |
|---|---|---|---|---|---|
| nss_ldap-251 | Oct 2006 | 14690 | |||
| nss-ldapd-0.1 | Dec 2006 | 1014 | 9230 | 10526 | |
| nss-ldapd-0.2 | Jun 2007 | 973 | 8685 | 10382 | |
| nss-ldapd-0.5 | Dec 2007 | 975 | 4472 | 6202 | |
| nss-ldapd-0.6 | Feb 2008 | 954 | 4551 | 6616 | |
| nss-ldapd-0.6.8 | Mar 2009 | 973 | 5162 | 7485 | |
| nss-pam-ldapd-0.7.0 | Sep 2009 | 920 | 621 | 5476 | 8383 |
| nss-pam-ldapd-0.7.13 | Dec 2010 | 878 | 513 | 5923 | 9207 |
| nss-pam-ldapd-0.8.0 | Dec 2010 | 1949 | 527 | 6209 | 10653 |
| nss-pam-ldapd-0.8.12 | Nov 2012 | 1996 | 598 | 7169 | 11809 |
| nss-pam-ldapd-0.9.0 | Apr 2013 | 2031 | 679 | 8563 | 13542 |
| nss-pam-ldapd-0.9.2 | Oct 2013 | 2034 | 679 | 8629 | 13621 |
The above numbers were generated using David A. Wheeler's 'SLOCCount' over the ANSI C source code and excluding the test code. These numbers are not always 100% comparable because in some releases some features were removed or added and differences in compatibility support.
More information
Some more information on the design and general notes on making modifications is available in the HACKING file.