git.sur5r.net Git - openldap/blob - contrib/slapd-modules/nssov/nss-ldapd/README

   1    nss-ldapd - NSS library for name lookups using LDAP
   2
   3    nss-ldapd is a fork from nss_ldap which was originally written by
   4    Luke Howard of PADL Software Pty Ltd.
   5
   6    http://www.padl.com/OSS/nss_ldap.html
   7
   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
  10    was rewritten.
  11    http://ch.tudelft.nl/~arthur/nss-ldapd/
  12
  13    Copyright (C) 1997-2006 Luke Howard
  14    Copyright (C) 2006, 2007 West Consulting
  15    Copyright (C) 2006, 2007, 2008 Arthur de Jong
  16
  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.
  21
  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.
  26
  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
  30    02110-1301 USA
  31
  32
  33 INTRODUCTION
  34 ============
  35
  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.
  39
  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.
  47
  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.
  51
  52 improvements over nss_ldap
  53 --------------------------
  54
  55 The fork from nss_ldap was done to implement some major design changes to fix
  56 some structural problems in the library.
  57
  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).
  61
  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.
  66
  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
  71   using nscd)
  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
  76
  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.
  81
  82 Note that the package currently cannot be used on the same system alongside
  83 nss_ldap.
  84
  85 supported C libraries
  86 ---------------------
  87
  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.
  91
  92 supported name databases
  93 ------------------------
  94
  95 Currently the following name databases are supported:
  96
  97   aliases, ethers, group, hosts, netgroup, networks, passwd, protocols, rpc,
  98   services and shadow
  99
 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
 105 and
 106   http://ldap.akbkhome.com/index.php/attribute/macAddress.html
 107
 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
 111 maps from LDAP.
 112
 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
 115 mailserver.
 116
 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.
 120
 121 supported LDAP libraries
 122 ------------------------
 123
 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
 126 too hard.
 127
 128 unsupported features
 129 --------------------
 130
 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
 140
 141 In general, the focus is to have the functionality that is present be well
 142 tested and supported.
 143
 144
 145 INSTALLATION
 146 ============
 147
 148 The nss-ldapd library uses autoconf and automake for building. Installing
 149 nss-ldapd should be as simple as:
 150
 151   % ./configure
 152   % make
 153   % make install
 154
 155 That said, it is a good idea to go first through the options of configure by
 156 running:
 157
 158   % ./configure --help
 159
 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.
 163
 164
 165 CONFIGURATION
 166 =============
 167
 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.
 172
 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:
 176
 177   # the following contain normal unix user and group information
 178   passwd:         files ldap
 179   group:          files ldap
 180   shadow:         files ldap
 181
 182   # hostname lookups through ldap before dns should work now
 183   hosts:          files ldap dns
 184   networks:       files ldap
 185
 186   # normal flat-file definitions
 187   protocols:      files ldap
 188   services:       files ldap
 189   ethers:         files ldap
 190   rpc:            files ldap
 191   netgroup:       ldap
 192
 193   # whether alias lookups really use NSS depends on the mail server
 194   aliases:        files ldap
 195
 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:
 200
 201   # the location of LDAP server
 202   uri ldap://localhost/
 203
 204   # search base for all queries.
 205   base dc=example,dc=net
 206
 207 service discovery through DNS
 208 -----------------------------
 209
 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.
 214
 215 To use this feature specify DNS as an uri in the configuration file and
 216 include something like the following in your zone:
 217
 218   _ldap._tcp  SRV  10 0  389  ldapserver
 219
 220
 221 LDAP SCHEMA
 222 ===========
 223
 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
 228 performance.
 229
 230 default attributes
 231 ------------------
 232
 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.
 236
 237 aliases (objectClass=nisMailAlias)
 238   cn                - alias name
 239   rfc822MailMember  - members of the alias (recipients)
 240 ethers (objectClass=ieee802Device)
 241   cn                - host name
 242   macAddress        - ethernet address
 243 group (objectClass=posixGroup)
 244   cn                - group name
 245   userPassword      - password
 246   gidNumber         - gid
 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)
 253   cn                - netgroup name
 254   nisNetgroupTriple - triplets describing netgroup entries
 255   memberNisNetgroup - reference to other netgroup
 256 networks (objectClass=ipNetwork)
 257   cn                - network name
 258   ipNetworkNumber   - network address
 259   ipNetmaskNumber   - network netmask
 260 passwd (objectClass=posixAccount)
 261   uid               - account name
 262   userPassword      - password
 263   uidNumber         - uid
 264   gidNumber         - gid
 265   gecos             - gecos
 266   cn                - gecos (if gecos is unset)
 267   homeDirectory     - home directory
 268   loginShell        - shell
 269 protocols (objectClass=ipProtocol)
 270   cn                - protocol name
 271   ipProtocolNumber  - protocol number
 272 rpc (oncRpc)
 273   cn                - rpc name
 274   oncRpcNumber      - rpc number
 275 services (objectClass=ipService)
 276   cn                - service name
 277   ipServicePort     - service port
 278   ipServiceProtocol - service protocol
 279 shadow (objectClass=shadowAccount)
 280   uid               - use name
 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
 289
 290 using Microsoft Active Directory
 291 --------------------------------
 292
 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.
 297
 298
 299 MISC NOTES
 300 ==========
 301
 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.
 307
 308
 309 REPORTING BUGS
 310 ==============
 311
 312 If you find any bugs or missing features please send email to
 313   arthur@ch.tudelft.nl
 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).