path: root/README

   nss-ldapd - NSS library for name lookups using LDAP

   nss-ldapd is a fork from nss_ldap which was orignally 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 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 is currently work in progress.

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 server
that handles the LDAP lookups. This simplifies the architecture and fixes some
scalability and locking problems with 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 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
  lookup no longer uses the ldap method

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.

supported name databases
------------------------

Currently the following name databases are supported:

  aliases, ethers, group, hosts, netgroup, networks, passwd, protocols, rpc,
  services and shadow

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 currently uses it's own method for getting the maps from LDAP.

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.1.30 but
adding support for other LDAP libraries with similar interfaces should not be
too hard.

The server part of the code is however still being refactored and cleaned up
and the LDAP part is still subject to change and simplification.


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.

paged results
-------------

The --enable-paged-results configure option implements handling of paged
results from the LDAP server in accordance with RFC2696.

When doing LDAP searches against a Microsoft Active Directory database, the
search results are divided into "chunks". A standard "ldap_search" against an
untweaked AD returns a maximum of 1000 entries. To get more than that, either
paging needs to be enabled or the page size needs to be increased in the
server. Enableing paging is obviously the cleaner solution.

The page size requested is 1000 entries, and is currently not configurable.
However, this should be fine in most setups.

Because of the way the page control is used, any LDAPv3 server that does not
implement paging should simply ignore it and return entries as normal;
however, this has not been fully tested yet.


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 LDAP 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

  # LDAP protocol version
  ldap_version 3


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) is also supported. A posixGroup can thus have the both memberUid and
uniqueMember attributes.

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 (nisMailAlias)
  cn                - alias name
  rfc822MailMember  - members
ethers (ieee802Device)
  cn                - host name
  macAddress        - ethernet address
group (posixGroup)
  cn                - group name
  userPassword      - should be readable by rootbinddn only
  memberUid         - members
  uniqueMember      - members
  gidNumber         - gid
hosts (ipHost)
  cn                - host name (and aliases)
  ipHostNumber      - addresses
netgroup (nisNetgroup)
  cn                - netgroup name
  nisNetgroupTriple - triplets describing netgroup entries
  memberNisNetgroup - reference to other netgroup
networks (ipNetwork)
  cn                - network name
  ipNetworkNumber   - network address
  ipNetmaskNumber   - network netmask
passwd (posixAccount)
  uid               - account name
  userPassword      - should be readable by rootbinddn only
  uidNumber         - uid
  gidNumber         - gid
  cn                - gecos
  homeDirectory     - home directory
  loginShell        - shell
  gecos             - gecos
protocols (ipProtocol)
  cn                - protocol name
  ipProtocolNumber  - protocol number
rpc (oncRpc)
  cn                - rpc name
  oncRpcNumber      - rpc number
services (ipService)
  cn                - service name
  ipServicePort     - service port
  ipServiceProtocol - service protocol
shadow (shadowAccount)
  uid               - use name
  userPassword      - should be readable by rootbinddn only
  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 passwd 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 default configuration file has some commented out attribute mappings for
such a setup.