1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
|
nss-pam-ldapd - NSS and PAM library for name lookups and authentication
using LDAP
nss-pam-ldapd started as nss-ldapd which was a fork from nss_ldap which was
originally written by Luke Howard of PADL Software Pty Ltd.
http://www.padl.com/OSS/nss_ldap.html
In 2006 Arthur de Jong of West Consuling forked the library to split it
into a thin NSS part and a server part. Most of the code was rewritten.
The software was renamed to nss-pam-ldapd when PAM code contributed by
Howard Chu for the OpenLDAP nssov module was integrated. Solaris
compatibility was developed by Ted C. Cheng of Symas Corporation.
http://arthurdejong.org/nss-pam-ldapd/
Copyright (C) 1997-2006 Luke Howard
Copyright (C) 2006-2007 West Consulting
Copyright (C) 2006-2010 Arthur de Jong
Copyright (C) 2009 Howard Chu
Copyright (C) 2010 Symas Corporation
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA
INTRODUCTION
============
This is the nss-pam-ldapd library which consists of an NSS module to do name
lookups to an LDAP directory server and a PAM module to do authentication to
an LDAP server. The NSS part of this library was forked from nss_ldap as
provided by Luke Howard of PADL Software Pty Ltd. The PAM module was mostly
provided by Howard Chu of the OpenLDAP project.
The NSS library allows distributing account, group, host and other
configuration information from a central LDAP server throughout an
organisation. Because LDAP is a hierarchical directory service, you can
distribute the information in a manner which reflects an organisational
structure. This contrasts with the flat, single domain policy of NIS. LDAP has
many of the advantages of NIS+ (security and scalability) without the
complexity. The system will work alongside your existing NIS, NIS+, DNS and
flat file name services.
The PAM library (module) can be used to perform authentication based on
information inside the LDAP directory.
Both libraries consist of a thin NSS or PAM part that communicates with a
local daemon (nslcd) that handles the LDAP lookups. This simplifies the
architecture and fixes some scalability and locking problems in the original
design of nss_ldap.
Also it is possible to use the thin NSS and PAM parts together with the nssov
overlay in the OpenLDAP server (slapd).
The three parts (NSS module, PAM module, and nslcd server) can be build
separately and are not tied together. This means that for instance you can
still use pam_ldap and use the NSS module from nss-pam-ldapd.
improvements over nss_ldap
--------------------------
The fork from nss_ldap was done to implement some major design changes to fix
some structural problems in the library.
The biggest of those problems were host name lookups through LDAP which could
cause deadlocks in most cases and some general name lookup problems during
booting (when the LDAP server was not started or not yet reachable).
A number of refactoring steps were done to simplify the code and improve
maintainability. Legacy code was removed and support for non-Linux operating
systems was initially removed to make the code more readable. Portability will
be re-added once the architecture stabilises.
The most practical improvements over nss_ldap are:
- the LDAP library is not loaded for every process doing LDAP lookups
- the number of connections to the LDAP server is limited, because not every
process will open it's own connection (this problem is also mitigated by
using nscd)
- hostname lookups should now be deadlock-free because the LDAP server name is
no longer looked up using the ldap method
- the setup is easier to debug because logging on the server component can be
enabled without affecting "normal" processes
This package runs a local daemon that will be enabled during the boot process.
This daemon will handle connections to the LDAP server and accept requests
through a named socket (/var/run/nslcd/socket). The thin NSS library will
proxy requests to the daemon.
Note that the package currently cannot be used on the same system alongside
nss_ldap.
comparison to pam_ldap
----------------------
The PAM module that is currently implemented contains functionality for
authentication, account management, password management and session
management. The nslcd daemon currently implements authentication,
authorisation and password modification. The OpenLDAP nssov overlay also
implements session functionality.
supported C libraries (for NSS module)
--------------------------------------
This library currently only supports the GNU C Library. Support for other C
libraries has been removed in a refactoring step. Compatibility code and
support for other C libraries will be added upon request.
supported name databases
------------------------
Currently the following name databases are supported:
aliases, ethers, group, hosts, netgroup, networks, passwd, protocols, rpc,
services and shadow
Note that for when using IPv6 hosts entries, the addresses in the LDAP
directory must be in their preferred form. The same is true for mac addresses
for the ethers database. Otherwise the address to entry lookups will not work.
For more details on the preferred form see
http://ldap.akbkhome.com/index.php/attribute/ipHostNumber.html
and
http://ldap.akbkhome.com/index.php/attribute/macAddress.html
automounter map lookups (which are also defined in /etc/nsswitch.conf) are not
supported because the NSS interface is not used for these. The common autofs
implementation (on GNU/Linux) currently uses it's own method for getting the
maps from LDAP.
Although aliases are exposed through NSS, most mail servers parse /etc/aliases
by themselves and getting aliases from LDAP requires some configuration in the
mail server.
The publickey, bootparams and netmasks are currently unsupported. Some
investigation should be done if these are needed for anything, which
interfaces should be exported and how the LDAP schema part should look like.
supported PAM implementation
----------------------------
The PAM module is currently only regularly tested on Linux PAM but other PAM
implementations should also work.
supported LDAP libraries
------------------------
The current version of nss-pam-ldapd has been developed with OpenLDAP 2.4 but
other LDAP libraries and older versions of OpenLDAP may also work.
unsupported features
--------------------
Since nss-pam-ldapd was forked from nss_ldap most of the features that came
with nss_ldap are available. The most important differences:
- the configuration file formats are not fully compatible
- nested groups are currently unsupported
- rootbinddn/rootbindpw support is removed and is not likely to return
For the PAM module some functionality is missing. Comparing it to pam_ldap:
- only BIND authentication is supported
- only LDAP password modify EXOP is supported as password changing mechanism
Some things work a little different in nss-pam-ldapd. For instance the
attribute defaults and overrides of nss_ldap are implemented with mapping
expressions and pam_ldap's pam_check_*_attr options can be implemented with
the pam_authz_search option.
INSTALLATION
============
The nss-pam-ldapd library uses autoconf and automake for building. Installing
nss-pam-ldapd should be as simple as:
% ./configure
% make
% make install
That said, it is a good idea to go first through the options of configure by
running:
% ./configure --help
The last step (make install) should install the libnss_ldap.so.* and
pam_ldap.so files and the daemon (nslcd). The boot process needs to be
manually modified to start the daemon at the right time.
Also, it is recommended to create a dedicated user for the nslcd daemon.
Configure this user in /etc/nslcd.conf using the uid and gid options.
CONFIGURATION
=============
After installation the name service switch configuration file
(/etc/nsswitch.conf) needs to be modified to do name lookups using the new
module. This consist mostly of adding ldap in the list of lookup methods in
the right place. See the nsswitch.conf(5) manual page for details on the
format. As an example the file could look a little like this:
# the following contain normal unix user and group information
passwd: files ldap
group: files ldap
shadow: files ldap
# hostname lookups through ldap before dns should work now
hosts: files ldap dns
networks: files ldap
# normal flat-file definitions
protocols: files ldap
services: files ldap
ethers: files ldap
rpc: files ldap
netgroup: ldap
# whether alias lookups really use NSS depends on the mail server
aliases: files ldap
Configuring PAM differs a little from platform to platform but this is a basic
set-up for files under /etc/pam.d:
auth sufficient pam_unix.so
auth sufficient pam_ldap.so use_first_pass
auth required pam_deny.so
account required pam_unix.so
account sufficient pam_ldap.so
account required pam_permit.so
session required pam_unix.so
session optional pam_ldap.so
password sufficient pam_unix.so nullok md5 shadow use_authtok
password sufficient pam_ldap.so try_first_pass
password required pam_deny.so
Lastly, a configuration file for nslcd (by default /etc/nslcd.conf) needs to
be made. See the shipped manual page for details on the format and options. It
should at the very least contain something like:
# the location of LDAP server
uri ldap://localhost/
# search base for all queries.
base dc=example,dc=net
service discovery through DNS
-----------------------------
nss-pam-ldapd supports looking up LDAP server names through DNS SRV records as
specified in RFC 2782. However, Priority and Weight are not considered
separately and a single list of servers in added as if they had been specified
with uri options in the configuration file.
To use this feature specify DNS as an uri in the configuration file and
include something like the following in your zone:
_ldap._tcp SRV 10 0 389 ldapserver
LDAP SCHEMA
===========
nss-pam-ldapd supports a wide range of possible LDAP schema configurations and
it can be customized heavily. The LDAP schema used is described in RFC 2307.
Groups with distinguished name members (instead of login names) (RFC 2307bis)
are also supported, although use of memberUid has much better performance (see
below for details).
default attributes
------------------
This paragraph describes the mapping between the NSS lookups and the LDAP
database. The mapping may be modified by changing the nslcd.conf configuration
file. See the nslcd.conf(5) manual page for details.
aliases (objectClass=nisMailAlias)
cn - alias name
rfc822MailMember - members of the alias (recipients)
ethers (objectClass=ieee802Device)
cn - host name
macAddress - ethernet address
group (objectClass=posixGroup)
cn - group name
userPassword - password
gidNumber - gid
memberUid - members (user names)
member - members (DN values)
hosts (objectClass=ipHost)
cn - host name (and aliases)
ipHostNumber - addresses
netgroup (objectClass=nisNetgroup)
cn - netgroup name
nisNetgroupTriple - triplets describing netgroup entries
memberNisNetgroup - reference to other netgroup
networks (objectClass=ipNetwork)
cn - network name
ipNetworkNumber - network address
passwd (objectClass=posixAccount)
uid - account name
userPassword - password
uidNumber - uid
gidNumber - gid
gecos - gecos
homeDirectory - home directory
loginShell - shell
protocols (objectClass=ipProtocol)
cn - protocol name
ipProtocolNumber - protocol number
rpc (oncRpc)
cn - rpc name
oncRpcNumber - rpc number
services (objectClass=ipService)
cn - service name
ipServicePort - service port
ipServiceProtocol - service protocol
shadow (objectClass=shadowAccount)
uid - use name
userPassword - password
shadowLastChange - last change of password
shadowMax - days before password may be changed
shadowMin - days after which password must be changed
shadowWarning - expiry warning
shadowInactive - account is disabled if no password is changed
shadowExpire - account expiration
shadowFlag - reserved field
using Microsoft Active Directory
--------------------------------
When using Microsoft Active Directory server (typically on Microsoft Windows
2000) some changes need to be made to the nslcd.conf configuration file. The
included sample configuration file has some commented out attribute mappings
for such a set-up.
group membership
----------------
Currently, two ways of specifying group membership are supported. The first,
by using the memberUid attribute, is the simplest and by far the fastest
(takes the least number of lookups). This attribute maps to user names with
the same values as the uid attribute would hold for posixAccount entries.
The second method is to use DN values in the member attribute (attribute
names can be changed by using the attribute mapping options as described in
the manual page). This is potentially a lot slower because in the worst case
every DN has to be looked up in the LDAP server to find the proper value for
the uid attribute.
If the DN value already contains a uid value (e.g. uid=arthur, dc=example,
dc=com) the lookup is skipped and the value from the DN is used. A cache is
maintained that saves the DN to uid translations for 15 minutes.
In all cases, users that are specified as member multiple times are returned
only once.
Currently, having nested groups by member values pointing to other groups,
as well as the memberOf attribute in posixAccount entries are unsupported.
case sensitivity
----------------
Most values in the NSS databases are considered case-sensitive (e.g. the user
"Foo" is a different user from the user "foo"). Most values in an LDAP
database are however considered case-insensitive. nss-pam-ldapd tries to solve
this problem by adding an extra filtering layer to ensure that e.g. when
looking for the user "foo" it will not return a user "Foo" that is found in
LDAP.
For the group, netgroup, passwd, protocols, rpc, services and shadow maps the
matches will be checked case-sensitively and for aliases, ethers, hosts and
networks matches will be case-insensitive (this seems to be what Glibc is
doing currently with flat files). Only searching for groups by user is done
case-insensitive. In all cases the case-use in the LDAP directory is returned.
Note that having entries that only differ in case is a bad idea and will
likely get you in trouble. One example of such a problem is that the DN
uid=test,dc=example,dc=com is the same as uid=TEST,dc=example,dc=com.
REPORTING BUGS
==============
If you find any bugs or missing features please send email to
nss-pam-ldapd-users@lists.arthurdejong.org
If you are using the Debian package you are encouraged to use the BTS. Please
include as much information as needed (platform, output of configure if
compilation fails, output of the failure, etc). Patches are more than welcome
(also see the file HACKING).
|