mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2025-01-12 10:54:48 +08:00
Code Issues Packages Projects Releases Wiki Activity
856a790a28
openldap/contrib/slapd-modules/nssov/nss-ldapd/README
Howard Chu c682cce27c nss-ldap overlay, built with nss-ldapd-0.6.2
2008-06-02 12:08:05 +00:00

318 lines
12 KiB
Plaintext
Raw Blame History

nss-ldapd - NSS library for name lookups using LDAP
nss-ldapd is 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.
http://ch.tudelft.nl/~arthur/nss-ldapd/
Copyright (C) 1997-2006 Luke Howard
Copyright (C) 2006, 2007 West Consulting
Copyright (C) 2006, 2007, 2008 Arthur de Jong
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-ldapd library which is an NSS module to do name lookups to an
LDAP directory server. This library was forked from nss_ldap as provided by
Luke Howard of PADL Software Pty Ltd.
The 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.
This library consists of a thin NSS part that communicates with a local daemon
that handles the LDAP lookups. This simplifies the architecture and fixes some
scalability and locking problems in the original design.
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).
With nss-ldapd a number of refactoring steps were taken 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 of nss-ldapd 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 NSS requests
from 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.
supported C libraries
---------------------
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 in due time 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->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 is exposed through NSS, most mailservers parse /etc/aliases
by themselves and getting aliases from LDAP requires some configuration in the
mailserver.
The publickey, bootparams and netmasks are currently also 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 LDAP libraries
------------------------
The current version of nss-ldapd has been developed with OpenLDAP 2.4 but
adding support for other LDAP libraries with similar interfaces should not be
too hard.
unsupported features
--------------------
Since nss-ldapd was forked from nss_ldap most of the features that came with
nss_ldap are available. However, not all features have extensively tested yet
and may cause problems.
- attribute value default and overrides have been removed (but may reappear
some day if requested)
- SSL/TLS support is untested but will be tested when the core code stabilizes
- the configuration file formats are not fully compatible
- nested groups are currently unsupported
- rootbinddn/rootbindpw support is removed and is not likely to return
In general, the focus is to have the functionality that is present be well
tested and supported.
INSTALLATION
============
The nss-ldapd library uses autoconf and automake for building. Installing
nss-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.* file and the
daemon (nslcd). The boot process needs to be manually modified to start the
daemon at the right time.
CONFIGURATION
=============
After installation the name service switch configuration file
(/etc/nsswitch.conf) needs to be modified to do name lookups using the new
module. Also, the nss-ldapd configuration file (specified at configure time)
needs to be modified to contain to the correct LDAP configuration.
Editing nsswitch.conf 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
Furthermore a configuration file (by default /etc/nss-ldapd.conf) needs to be
made. The location of this file can be specified with configure. See the
shipped manual page for details on the format and options. It should at 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-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-ldapd supports a wide range of possible LDAP schema configurations.
Furthermore 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.
default attributes
------------------
This paragraph describes the mapping between the NSS lookups and the LDAP
database. The mapping may be modified by changeging the nss-ldapd.conf
configuration file. See the nss-ldapd.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)
uniqueMember - 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
ipNetmaskNumber - network netmask
passwd (objectClass=posixAccount)
uid - account name
userPassword - password
uidNumber - uid
gidNumber - gid
gecos - gecos
cn - gecos (if gecos is unset)
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 nss-ldapd.conf configuration file.
The included sample configuration file has some commented out attribute
mappings for such a set-up.
MISC NOTES
==========
Most values in the NSS databases are considered case-sensitive (e.g. the user
"Foo" is a different user from "foo"). Values in an LDAP database are however
case-insensitive. This may cause problems in some corner cases, especially
when nscd is used for caching. For example, when doing a lookup for the user
"Foo" the user "foo" will be returned if it exists in the database.
REPORTING BUGS
==============
If you find any bugs or missing features please send email to
arthur@ch.tudelft.nl
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).
Reference in New Issue View Git Blame Copy Permalink