1 nss-ldapd - NSS library for name lookups using LDAP
3 nss-ldapd is a fork from nss_ldap which was originally written by
4 Luke Howard of PADL Software Pty Ltd.
6 http://www.padl.com/OSS/nss_ldap.html
8 In 2006 Arthur de Jong of West Consuling forked the library to
9 split it into a thin NSS part and a server part. Most of the code
11 http://ch.tudelft.nl/~arthur/nss-ldapd/
13 Copyright (C) 1997-2006 Luke Howard
14 Copyright (C) 2006, 2007 West Consulting
15 Copyright (C) 2006, 2007, 2008 Arthur de Jong
17 This library is free software; you can redistribute it and/or
18 modify it under the terms of the GNU Lesser General Public
19 License as published by the Free Software Foundation; either
20 version 2.1 of the License, or (at your option) any later version.
22 This library is distributed in the hope that it will be useful,
23 but WITHOUT ANY WARRANTY; without even the implied warranty of
24 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
25 Lesser General Public License for more details.
27 You should have received a copy of the GNU Lesser General Public
28 License along with this library; if not, write to the Free Software
29 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
36 This is the nss-ldapd library which is an NSS module to do name lookups to an
37 LDAP directory server. This library was forked from nss_ldap as provided by
38 Luke Howard of PADL Software Pty Ltd.
40 The library allows distributing account, group, host and other configuration
41 information from a central LDAP server throughout an organisation. Because
42 LDAP is a hierarchical directory service, you can distribute the information
43 in a manner which reflects an organisational structure. This contrasts with
44 the flat, single domain policy of NIS. LDAP has many of the advantages of NIS+
45 (security and scalability) without the complexity. The system will work
46 alongside your existing NIS, NIS+, DNS and flat file name services.
48 This library consists of a thin NSS part that communicates with a local daemon
49 that handles the LDAP lookups. This simplifies the architecture and fixes some
50 scalability and locking problems in the original design.
52 improvements over nss_ldap
53 --------------------------
55 The fork from nss_ldap was done to implement some major design changes to fix
56 some structural problems in the library.
58 The biggest of those problems were host name lookups through LDAP which could
59 cause deadlocks in most cases and some general name lookup problems during
60 booting (when the LDAP server was not started or not yet reachable).
62 With nss-ldapd a number of refactoring steps were taken to simplify the code
63 and improve maintainability. Legacy code was removed and support for non-Linux
64 operating systems was initially removed to make the code more readable.
65 Portability will be re-added once the architecture stabilises.
67 The most practical improvements of nss-ldapd over nss_ldap are:
68 - the LDAP library is not loaded for every process doing LDAP lookups
69 - the number of connections to the LDAP server is limited, because not every
70 process will open it's own connection (this problem is also mitigated by
72 - hostname lookups should now be deadlock-free because the LDAP server name is
73 no longer looked up using the ldap method
74 - the setup is easier to debug because logging on the server component can be
75 enabled without affecting "normal" processes
77 This package runs a local daemon that will be enabled during the boot process.
78 This daemon will handle connections to the LDAP server and accept NSS requests
79 from a named socket (/var/run/nslcd/socket). The thin NSS library will proxy
80 requests to the daemon.
82 Note that the package currently cannot be used on the same system alongside
88 This library currently only supports the GNU C Library. Support for other C
89 libraries has been removed in a refactoring step. Compatibility code and
90 support for other C libraries will be added in due time upon request.
92 supported name databases
93 ------------------------
95 Currently the following name databases are supported:
97 aliases, ethers, group, hosts, netgroup, networks, passwd, protocols, rpc,
100 Note that for when using IPv6 hosts entries, the addresses in the LDAP
101 directory must be in their preferred form. The same is true for mac addresses
102 for the ethers database. Otherwise the address->entry lookups will not work.
103 For more details on the preferred form see
104 http://ldap.akbkhome.com/index.php/attribute/ipHostNumber.html
106 http://ldap.akbkhome.com/index.php/attribute/macAddress.html
108 automounter map lookups (which are also defined in /etc/nsswitch.conf) are not
109 supported because the NSS interface is not used for these. The common autofs
110 implementation (on GNU/Linux) currently uses it's own method for getting the
113 Although aliases is exposed through NSS, most mailservers parse /etc/aliases
114 by themselves and getting aliases from LDAP requires some configuration in the
117 The publickey, bootparams and netmasks are currently also unsupported. Some
118 investigation should be done if these are needed for anything, which
119 interfaces should be exported and how the LDAP schema part should look like.
121 supported LDAP libraries
122 ------------------------
124 The current version of nss-ldapd has been developed with OpenLDAP 2.4 but
125 adding support for other LDAP libraries with similar interfaces should not be
131 Since nss-ldapd was forked from nss_ldap most of the features that came with
132 nss_ldap are available. However, not all features have extensively tested yet
133 and may cause problems.
134 - attribute value default and overrides have been removed (but may reappear
135 some day if requested)
136 - SSL/TLS support is untested but will be tested when the core code stabilizes
137 - the configuration file formats are not fully compatible
138 - nested groups are currently unsupported
139 - rootbinddn/rootbindpw support is removed and is not likely to return
141 In general, the focus is to have the functionality that is present be well
142 tested and supported.
148 The nss-ldapd library uses autoconf and automake for building. Installing
149 nss-ldapd should be as simple as:
155 That said, it is a good idea to go first through the options of configure by
160 The last step (make install) should install the libnss_ldap.so.* file and the
161 daemon (nslcd). The boot process needs to be manually modified to start the
162 daemon at the right time.
168 After installation the name service switch configuration file
169 (/etc/nsswitch.conf) needs to be modified to do name lookups using the new
170 module. Also, the nss-ldapd configuration file (specified at configure time)
171 needs to be modified to contain to the correct LDAP configuration.
173 Editing nsswitch.conf consist mostly of adding ldap in the list of lookup
174 methods in the right place. See the nsswitch.conf(5) manual page for details
175 on the format. As an example the file could look a little like this:
177 # the following contain normal unix user and group information
182 # hostname lookups through ldap before dns should work now
183 hosts: files ldap dns
186 # normal flat-file definitions
187 protocols: files ldap
193 # whether alias lookups really use NSS depends on the mail server
196 Furthermore a configuration file (by default /etc/nss-ldapd.conf) needs to be
197 made. The location of this file can be specified with configure. See the
198 shipped manual page for details on the format and options. It should at least
199 contain something like:
201 # the location of LDAP server
202 uri ldap://localhost/
204 # search base for all queries.
205 base dc=example,dc=net
207 service discovery through DNS
208 -----------------------------
210 nss-ldapd supports looking up LDAP server names through DNS SRV records as
211 specified in RFC 2782. However, Priority and Weight are not considered
212 separately and a single list of servers in added as if they had been specified
213 with uri options in the configuration file.
215 To use this feature specify DNS as an uri in the configuration file and
216 include something like the following in your zone:
218 _ldap._tcp SRV 10 0 389 ldapserver
224 nss-ldapd supports a wide range of possible LDAP schema configurations.
225 Furthermore it can be customized heavily. The LDAP schema used is described in
226 RFC 2307. Groups with distinguished name members (instead of login names) (RFC
227 2307bis) are also supported, although use of memberUid has much better
233 This paragraph describes the mapping between the NSS lookups and the LDAP
234 database. The mapping may be modified by changeging the nss-ldapd.conf
235 configuration file. See the nss-ldapd.conf(5) manual page for details.
237 aliases (objectClass=nisMailAlias)
239 rfc822MailMember - members of the alias (recipients)
240 ethers (objectClass=ieee802Device)
242 macAddress - ethernet address
243 group (objectClass=posixGroup)
245 userPassword - password
247 memberUid - members (user names)
248 uniqueMember - members (DN values)
249 hosts (objectClass=ipHost)
250 cn - host name (and aliases)
251 ipHostNumber - addresses
252 netgroup (objectClass=nisNetgroup)
254 nisNetgroupTriple - triplets describing netgroup entries
255 memberNisNetgroup - reference to other netgroup
256 networks (objectClass=ipNetwork)
258 ipNetworkNumber - network address
259 ipNetmaskNumber - network netmask
260 passwd (objectClass=posixAccount)
262 userPassword - password
266 cn - gecos (if gecos is unset)
267 homeDirectory - home directory
269 protocols (objectClass=ipProtocol)
271 ipProtocolNumber - protocol number
274 oncRpcNumber - rpc number
275 services (objectClass=ipService)
277 ipServicePort - service port
278 ipServiceProtocol - service protocol
279 shadow (objectClass=shadowAccount)
281 userPassword - password
282 shadowLastChange - last change of password
283 shadowMax - days before password may be changed
284 shadowMin - days after which password must be changed
285 shadowWarning - expiry warning
286 shadowInactive - account is disabled if no password is changed
287 shadowExpire - account expiration
288 shadowFlag - reserved field
290 using Microsoft Active Directory
291 --------------------------------
293 When using Microsoft Active Directory server (typically on Microsoft Windows
294 2000) some changes need to be made to the nss-ldapd.conf configuration file.
295 The included sample configuration file has some commented out attribute
296 mappings for such a set-up.
302 Most values in the NSS databases are considered case-sensitive (e.g. the user
303 "Foo" is a different user from "foo"). Values in an LDAP database are however
304 case-insensitive. This may cause problems in some corner cases, especially
305 when nscd is used for caching. For example, when doing a lookup for the user
306 "Foo" the user "foo" will be returned if it exists in the database.
312 If you find any bugs or missing features please send email to
314 If you are using the Debian package you are encouraged to use the BTS.
315 Please include as much information as needed (platform, output of configure
316 if compilation fails, output of the failure, etc). Patches are more than
317 welcome (also see the file HACKING).