From a44da19368f242cb012dd16254f4fb668cc6a891 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 28 Aug 2014 16:56:45 +0300 Subject: Update docs --- doc/smap.texi | 123 +++++++++++++++++++++++++++++++++++++++++++--------------- 1 file 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 -- cgit v1.2.1