ldap_dn_filter option is documented; now fetching only needed attributes in LDAP search requests (EJAB-1204)

1 files changed, 16 insertions, 1 deletions

diff --git a/doc/guide.tex b/doc/guide.tex
index a6c289ed0..20f6b17c0 100644
--- a/doc/guide.tex
+++ b/doc/guide.tex
@@ -2238,7 +2238,22 @@ You can authenticate users against an LDAP directory. Available options are:
   not forget to close brackets and do not use superfluous whitespaces. Also you
   \emph{must not} use \option{ldap\_uidattr} attribute in filter because this
   attribute will be substituted in LDAP filter automatically.
-
+  \titem{\{ldap\_dn\_filter, \{ Filter, FilterAttrs \}\}}\ind{options!ldap\_dn\_filter}
+  This filter is applied on the results returned by the main filter. This filter
+  performs additional LDAP lookup to make the complete result. This is useful
+  when you are unable to define all filter rules in \term{ldap\_filter}. You
+  can define \term{"\%u"}, \term{"\%d"}, \term{"\%s"} and \term{"\%D"} pattern
+  variables in Filter: \term{"\%u"} is replaced by a user's part of a JID,
+  \term{"\%d"} is replaced by the corresponding domain (virtual host),
+  all \term{"\%s"} variables are consecutively replaced by values of FilterAttrs
+  attributes and \term{"\%D"} is replaced by Distinguished Name. By default
+  \term{ldap\_dn\_filter} is undefined.
+  Example:
+\begin{verbatim}
+{ldap_dn_filter, {"(&(name=%s)(owner=%D)(user=%u@%d))", ["sn"]}}.
+\end{verbatim}
+  Since this filter makes additional LDAP lookups, use it only in the
+  last resort: try to define all filter rules in \term{ldap\_filter} if possible.
   \titem{\{ldap\_local\_filter, Filter\}}\ind{options!ldap\_local\_filter}
   If you can't use \term{ldap\_filter} due to performance reasons
   (the LDAP server has many users registered),