update documentation

git-svn-id: http://arthurdejong.org/svn/nss-pam-ldapd/nss-pam-ldapd@1117 ef36b2f9-881f-0410-afb5-c4e39611909c

4 files changed, 112 insertions, 101 deletions

diff --git a/HACKING b/HACKING
index 84a86d3..3983651 100644
--- a/HACKING
+++ b/HACKING
@@ -33,7 +33,7 @@ BUILD DEPENDENCIES
 
 For building svn snapshots the following tools are needed:
 
-* autoconf (2.61 is used but 2.59 is minimal)
+* autoconf (2.65 is used but 2.61 is minimal)
 * automake (1.11 is used)
 
 and of course the usual build tools (gcc/make/etc). Also see debian/control
@@ -51,7 +51,7 @@ RELEASE VERSIONING
 A new versioning scheme was chosen over the nss_ldap release scheme. The
 scheme is a simple major.minor.micro numbering. Until a 1.0 release is made
 the code will be considered work in progress. The interfaces may change and
-features may be added and removed.
+features may be added or removed.
 
 
 GENERAL DESIGN
@@ -67,7 +67,7 @@ system.
 
 Both these parts translate the queries in a higher-level simple protocol used
 to communicate with the nslcd daemon. This daemon translates the requests into
-LDAP searches. As a result the NSS and PAM modules don't need to known
+LDAP searches. As a result, the NSS and PAM modules don't need to known
 anything about LDAP (in fact replacing it with another lookup method should be
 very simple) and don't have to link with the LDAP libraries.
 
@@ -94,9 +94,9 @@ The NSS module is implemented in the nss directory. The functions are split
 into files according to the database they support. Functions look like:
 
 _nss_ldap_FUNCTION_r(...)
-  This function opens the connection to the nslcd (with a time-out) builds the
-  correct data structures and does a request (write()) to the nslcd waiting
-  for an answer (again with a time-out)
+  This function opens the connection to the nslcd (with a time-out), builds
+  the correct data structures and does a request (write()) to the nslcd
+  waiting for an answer (again with a time-out)
 
 The complete list of exported functions can be found in exports.linux and
 prototypes.h. The NSS interface seems to be fairly libc-specific and is
@@ -108,7 +108,6 @@ these functions. Part of this is defined in the common/nslcd-prot.h file and
 the NSS-specific stuff is in nss/common.h.
 
 Some useful links:
-http://mirrors.usc.edu/pub/gnu/Manuals/glibc-2.2.3/html_chapter/libc_28.html#SEC596
 http://www.gnu.org/software/libc/manual/html_node/index.html
 
 
@@ -117,13 +116,13 @@ PAM MODULE
 
 The PAM module is implemented in the pam directory. Implementation is fairly
 straight-forward. The PAM module stores some state between PAM calls in a
-struct. The calls to nslcd are however stateless. The PAM module may however
-supply some information that help lookups (most notably DNs of user entries).
+struct. The calls to nslcd are however stateless. The PAM module may supply
+some information that help lookups (most notably DNs of user entries).
 
 Care must be taken with the communication because the nslcd requests are not
 authenticated (e.g. changing passwords requests should include all
-credentials). This is where the PAM module is different from the NSS module.
-The PAM module could result in state changes on the LDAP server.
+credentials). The PAM requests may result in state changes on the LDAP server
+and this is where they are most notably different from the NSS requests.
 
 Some useful links:
 http://www.kernel.org/pub/linux/libs/pam/
@@ -174,11 +173,11 @@ nslcd_FUNCION(...)
 SECURITY NOTES
 ==============
 
-This design does open up the system to more potential security issues as there
-is now a local interface to a daemon with privileges. Before processes could
-only potentially exploit bugs in the library and gain the privileges of the
-process that was doing the name lookups. In this case the privileges of the
-daemon are potentially exposed.
+This design does open up the system to more potential security issues because
+there is now a local interface to a daemon with privileges. Before (with
+nss_ldap) processes could only potentially exploit bugs in the library and
+gain the privileges of the process that was doing the name lookups. In this
+case the privileges of the daemon are potentially exposed.
 
 Extra care should be taken with processes that normally require extra
 privileges (getting shadow entries, authentication, updating session
@@ -189,8 +188,8 @@ needs to check the userid of the caller or the request needs to contain the
 needed credentials itself.
 
 
-TEST SETUP
-==========
+TEST SET-UP
+===========
 
 In the test directory there are a number of tests available. See the file
 README in the test directory for more details.
diff --git a/README b/README
index 3edae47..36cddc7 100644
--- a/README
+++ b/README
@@ -16,7 +16,7 @@
 
    Copyright (C) 1997-2006 Luke Howard
    Copyright (C) 2006, 2007 West Consulting
-   Copyright (C) 2006, 2007, 2008, 2009 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2009, 2010 Arthur de Jong
    Copyright (C) 2009 Howard Chu
 
    This library is free software; you can redistribute it and/or
@@ -59,7 +59,7 @@ 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.
+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).
@@ -94,9 +94,9 @@ The most practical improvements over nss_ldap are:
   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.
+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.
@@ -105,21 +105,17 @@ comparison to pam_ldap
 ----------------------
 
 The PAM module that is currently implemented contains functionality for
-authentication, account management, password management and session management
-but only authentication is currently implemented in the nslcd daemon. The
-OpenLDAP nssov overlay implements more functionality.
+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
----------------------
+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 in due time upon request.
-
-supported PAM implementation
-----------------------------
-
-The PAM module is currently only regularly tested on Linux PAM
+support for other C libraries will be added upon request.
 
 supported name databases
 ------------------------
@@ -142,41 +138,43 @@ 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
+Although aliases are exposed through NSS, most mail servers parse /etc/aliases
 by themselves and getting aliases from LDAP requires some configuration in the
-mailserver.
+mail server.
 
-The publickey, bootparams and netmasks are currently also unsupported. Some
+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
-adding support for other LDAP libraries with similar interfaces should not be
-too hard.
+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. However, not all features have extensively tested
-yet and may cause problems.
-- attribute value defaults and overrides have been removed (but may reappear
-  some day if requested)
+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 a lot more functionality is missing. Comparing it to
-pam_ldap:
-- only BIND authentication is implemented
-- no authorisation checks are performed
-- password changing is under development
+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
 
-In general, the focus is to have the functionality that is present be well
-tested and supported and add more features when they are needed.
+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
@@ -198,7 +196,7 @@ 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 to run the nslcd daemon as.
+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.
 
 
@@ -207,12 +205,9 @@ 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-pam-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:
+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
@@ -233,10 +228,27 @@ on the format. As an example the file could look a little like this:
   # whether alias lookups really use NSS depends on the mail server
   aliases:        files ldap
 
-Furthermore a configuration file (by default /etc/nslcd.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:
+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/
@@ -261,18 +273,18 @@ include something like the following in your zone:
 LDAP SCHEMA
 ===========
 
-nss-pam-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 (see below for details).
+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 changeging the nslcd.conf
-configuration file. See the nslcd.conf(5) manual page for details.
+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
@@ -331,16 +343,16 @@ 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.
+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 amount of lookups). This attributes maps to user names with
+(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 uniqueMember attribute (attribute
@@ -351,8 +363,7 @@ 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 holds on to DN to uid translations for 15 minutes (see
-DN2UID_CACHE_TIMEOUT in nslcd/passwd.c).
+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.
@@ -365,20 +376,20 @@ 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"). Values in an LDAP database are
-however cosidered case-insensitive. nss-pam-ldapd tries to solve this problem
-by adding an extra filtering layer and ensure that e.g. when looking for the
-user "foo" it will not return a user "Foo" that is found in LDAP.
+"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 member the
-username matching is done case-insensitive. Note that in all cases the
-case-use in the LDAP directory is returned.
+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 however 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
+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.
 
 
diff --git a/man/nslcd.8.xml b/man/nslcd.8.xml
index 1d6072b..f5d3f26 100644
--- a/man/nslcd.8.xml
+++ b/man/nslcd.8.xml
@@ -58,9 +58,9 @@
  <refsect1 id="description">
   <title>Description</title>
   <para>
-   <command>nslcd</command> is a daemon that will do LDAP queries
-   for local processes based on a simple configuration
-   file.
+   <command>nslcd</command> is a daemon that will do LDAP queries for local
+   processes that want to do user, group and other naming lookups (NSS) or do
+   user authentication, authorisation or password modification (PAM).
   </para>
   <para>
    <command>nslcd</command> is configured through a configuration file
diff --git a/man/nslcd.conf.5.xml b/man/nslcd.conf.5.xml
index 9eb7759..eb56e9a 100644
--- a/man/nslcd.conf.5.xml
+++ b/man/nslcd.conf.5.xml
@@ -60,15 +60,15 @@
     configuration information for running <command>nslcd</command> (see
     <citerefentry><refentrytitle>nslcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>).
     The file contains options, one on each line, defining the way
-    <acronym>NSS</acronym> lookups are mapped onto
-    <acronym>LDAP</acronym> lookups.
+    <acronym>NSS</acronym> lookups and <acronym>PAM</acronym> actions
+    are mapped to <acronym>LDAP</acronym> lookups.
   </para>
  </refsect1>
 
  <refsect1 id="options">
   <title>Options</title>
 
-  <refsect2 id='runtime_options'>
+  <refsect2 id="runtime_options">
    <title>Runtime options</title>
    <variablelist>
 
@@ -87,7 +87,7 @@
      <term><option>uid</option> <replaceable>UID</replaceable></term>
      <listitem>
       <para>
-       This specifies  which user id with which the daemon should be run.
+       This specifies the user id with which the daemon should be run.
        This can be a numerical id or a symbolic value.
        If no uid is specified no attempt to change the user will be made.
        Note that you should use values that don't need <acronym>LDAP</acronym>
@@ -100,7 +100,7 @@
      <term><option>gid</option> <replaceable>GID</replaceable></term>
      <listitem>
       <para>
-       This specifies  which group id with which the daemon should be run.
+       This specifies the group id with which the daemon should be run.
        This can be a numerical id or a symbolic value.
        If no gid is specified no attempt to change the group will be made.
        Note that you should use values that don't need <acronym>LDAP</acronym>
@@ -112,7 +112,7 @@
    </variablelist>
   </refsect2>
 
-  <refsect2 id='general_connection_options'>
+  <refsect2 id="general_connection_options">
    <title>General connection options</title>
    <variablelist>
 
@@ -202,7 +202,7 @@
   </refsect2>
 
 <!-- DO NOT DOCUMENT FOR NOW BECAUSE IT'S NOT SUPPORTED
-  <refsect2 id='sasl_authentication_options'>
+  <refsect2 id="sasl_authentication_options">
    <title><acronym>SASL</acronym> authentication options</title>
    <variablelist>
 
@@ -273,7 +273,7 @@
   </refsect2>
 -->
 
-  <refsect2 id='kerberos_authentication_options'>
+  <refsect2 id="kerberos_authentication_options">
    <title>Kerberos authentication options</title>
    <variablelist>
 
@@ -289,7 +289,7 @@
    </variablelist>
   </refsect2>
 
-  <refsect2 id='search_mapping_options'>
+  <refsect2 id="search_mapping_options">
    <title>Search/mapping options</title>
    <variablelist>
 
@@ -412,7 +412,7 @@
    </variablelist>
   </refsect2>
 
-  <refsect2 id='timing_reconnect_options'>
+  <refsect2 id="timing_reconnect_options">
    <title>Timing/reconnect options</title>
    <variablelist>
 
@@ -423,7 +423,7 @@
        Specifies the time limit (in seconds) to use when connecting to the
        directory server.
        This is distinct from the time limit specified in
-       <option>timelimit</option> and affects the setup of the connection only.
+       <option>timelimit</option> and affects the set-up of the connection only.
        Note that not all <acronym>LDAP</acronym> client libraries have support
        for setting the connection time out.
        The default <option>bind_timelimit</option> is 10 seconds.
@@ -483,8 +483,9 @@
    <para>
     Note that the reconnect logic as described above is the mechanism that
     is used between <command>nslcd</command> and the <acronym>LDAP</acronym>
-    server. The mechanism between the <acronym>NSS</acronym> client library
-    and <command>nslcd</command> is simpler with a fixed compiled-in
+    server. The mechanism between the <acronym>NSS</acronym> and
+    <acronym>PAM</acronym> client libraries on one end and
+    <command>nslcd</command> on the other is simpler with a fixed compiled-in
     time out of a 10 seconds for writing to <command>nslcd</command> and
     a time out of 60 seconds for reading answers.
     <command>nslcd</command> itself has a read time out of 0.5 seconds
@@ -493,7 +494,7 @@
 
   </refsect2>
 
-  <refsect2 id='ssl_tls_options'>
+  <refsect2 id="ssl_tls_options">
    <title><acronym>SSL</acronym>/<acronym>TLS</acronym> options</title>
    <variablelist>
 
@@ -587,7 +588,7 @@
    </variablelist>
   </refsect2>
 
-  <refsect2 id='other_options'>
+  <refsect2 id="other_options">
    <title>Other options</title>
    <variablelist>