Update docs

1 files changed, 92 insertions, 31 deletions

diff --git a/doc/smap.texi b/doc/smap.texi
index 4bc5325..cf9b56f 100644
--- a/doc/smap.texi
+++ b/doc/smap.texi
@@ -2719,8 +2719,8 @@ Default value is @samp{NOTFOUND}.
 Directory Access Protocol.  The configuration is similar to that
 of SQL modules:
 
-  The @acronym{LDAP} parameters may be configured either globally, when
-loading the module, or locally, when defining a smap database.  If a
+  @acronym{LDAP} parameters may be configured either globally, when
+loading the module, or locally, when defining a smap database.  If the
 database definition lacks some configuration statements, it looks them
 up in a global definition.
 
@@ -2734,6 +2734,33 @@ template} is expanded and the result is used as a response.
 Otherwise, if the query produced an empty set, the smap database uses
 the @dfn{negative reply template} to create the response.
 
+@flindex /etc/ldap.conf
+  The module gets its configuration from the file
+@file{/etc/ldap.conf} and from module and database command line.  The 
+settings from the command line override those from
+@file{/etc/ldap.conf}.  Alternative configuration file can be
+specified using the @option{config-file} option.
+The subsections that follow discuss the keywords meaningful for the
+@command{ldap} module.  Unless explicitly stated otherwise, these can
+be used in the command line as well as in the configuration file.  For
+compatibility with other @acronym{LDAP} software, keywords in the
+configuration file are case-insensitive.  Unrecognized keywords
+appearing in the configuration file are silently ignored.  You can use
+the @samp{ldap.2} debug level to get a listing of those.  This can be
+useful to trace possible typos.
+
+Unrecognized keywords appearing in the command line are treated as
+errors, as usual.
+
+@kwindex config-file
+The only keyword that can be used only in the command line is
+@option{config-file}:
+
+@table @option
+@item config-file=@var{file}
+  Read configuration from file @var{file} instead of @file{/etc/ldap.conf}.
+@end table
+
 @menu
 * LDAP Configuration::
 * LDAP Filter and SMAP Replies::
@@ -2742,17 +2769,26 @@ the @dfn{negative reply template} to create the response.
 @node LDAP Configuration
 @subsection LDAP Configuration
 
-@flindex /etc/ldap.conf
-The @acronym{LDAP} configuration is read from the file
-@file{/etc/ldap.conf} and from module and database command line.  The
-settings from the command line override those from
-@file{/etc/ldap.conf}.  Alternative configuration file can be
-specified using the @option{config-file} option.
+The following keywords configure access to the @acronym{LDAP} database:
 
 @table @option
-@kwindex config-file
-@item config-file=@var{file}
-  Read configuration from file @var{file} instead of @file{/etc/ldap.conf}.
+@kwindex base
+@item base=@var{string}
+  Sets the default base DN for ldap operations.  The base must be
+specified as a Distinguished Name in LDAP format.
+                              
+@kwindex binddn
+@item binddn=@var{dn}
+  The DN to bind as.
+  
+@kwindex bindpw
+@item bindpw=@var{password}
+  Password for @code{binddn}.
+  
+@kwindex bindpwfile
+@item bindpwfile=@var{file}
+  Read password from @var{file}.  This is a safer alternative to
+@option{bindpw}.  
 
 @kwindex tls-cacert
 @kwindex tls_cacert
@@ -2772,42 +2808,67 @@ address of the remote server.  Optional @var{port} specifies the TCP
 port to use instead of the default one.  For @samp{ldapi}, @var{name}
 is the pathname of the UNIX socket and @var{port} is not used.  Note,
 that directory separators must be URL-encoded (using @samp{%2F}
-instead of @samp{/}).
-  
-@kwindex base
-@item base=@var{string}
-  Sets the default base DN for ldap operations.  The base must be
-specified as a Distinguished Name in LDAP format.
-                              
-@kwindex binddn
-@item binddn=@var{dn}
-  The DN to bind as.
-  
-@kwindex bindpw
-@item bindpw=@var{password}
-  Password for @code{binddn}.
-  
-@kwindex bindpwfile
-@item bindpwfile=@var{file}
-  Read password from @var{file}.  This is a safer alternative to
-@option{bindpw}.  
+instead of @samp{/}).  
 @end table
 
 @node LDAP Filter and SMAP Replies
 @subsection LDAP Filter and SMAP Replies
 
+The following keywords configure @acronym{LDAP} lookups and
+replies.
+
 @table @option
 @kwindex filter
 @item filter=@var{pattern}
-  
+  Specifies @acronym{LDAP} filter.  The @var{pattern} can use the
+usual variables (@pxref{expansion}).  For example:
+
+@example
+database user ldap filter=(&(objectClass=posixAccount)(uid=$key))
+@end example
+
+There is no default for this option, so it is mandatory.
+@end table
+
+  Replies are configured via the following three keywords:
+
+@table @option
 @kwindex positive-reply
 @item positive-reply=@var{reply}
+  Defines a positive reply string.  It is used when the @acronym{LDAP}
+lookup using the defined filter returned one or more objects.  Only
+the first returned object is used.  The @var{reply} string can contain
+the basic @command{smap} variables @samp{$db}, @samp{$map}, and
+@samp{$key}.  It can also refer to values of any attribute from the
+returned object using the variable notation.  For example:
+
+@example
+positive-reply="OK $uid"
+@end example
+
+@noindent
+returns the string @samp{OK} followed by the value of the @option{uid}
+attribute.
+
+The default positive reply string is @samp{OK}.
 
 @kwindex negative-reply
 @item negative-reply=@var{reply}
 
+Defines the negative reply string, which is used when the
+@acronym{LDAP} lookup returns empy set of objects.  The @var{reply}
+string can contain the basic @command{smap} variables @samp{$db},
+@samp{$map}, and @samp{$key}.
+
+The default negative reply string is @samp{NOTFOUND}.
+
 @kwindex onerror-reply
 @item onerror-reply=@var{reply}
+Defines the string to be returned if the @acronym{LDAP} lookup fails.
+The @var{reply} argument can contain the basic @command{smap}
+variables @samp{$db}, @samp{$map}, and @samp{$key}.
+
+The default value is @samp{NOTFOUND}.
 @end table
 
 @node sed