[Emacs-diffs] master a6d4651 15/17: Update LDAP configuration section of EUDC manual

[Stefan Monnier]

branch: master
commit a6d46519f5a4c07fd31dae6ad71020125b3e4690
Author: Thomas Fitzsimmons <address@hidden>
Commit: Thomas Fitzsimmons <address@hidden>

    Update LDAP configuration section of EUDC manual
    
    * eudc.texi (LDAP Configuration): Rename from LDAP Requirements
    and provide configuration examples.
---
 doc/misc/ChangeLog |    5 ++
 doc/misc/eudc.texi |  130 ++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 127 insertions(+), 8 deletions(-)

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 416d44d..a02e539 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2014-11-13  Thomas Fitzsimmons  <address@hidden>
+
+       * eudc.texi (LDAP Configuration): Rename from LDAP Requirements
+       and provide configuration examples.
+
 2014-10-20  Glenn Morris  <address@hidden>
 
        * Version 24.4 released.
diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index a54a37a..66867cb 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -137,7 +137,7 @@ location, address@hidden More information about LDAP can be 
found at
 @url{http://www.openldap.org/}.
 
 EUDC requires external support to access LDAP directory servers
-(@pxref{LDAP Requirements})
+(@pxref{LDAP Configuration})
 
 
 @node CCSO PH/QI
@@ -213,17 +213,131 @@ email composition buffers (@pxref{Inline Query 
Expansion})
 @end lisp
 
 @menu
-* LDAP Requirements::           EUDC needs external support for LDAP
+* LDAP Configuration::           EUDC needs external support for LDAP
 @end menu
 
address@hidden LDAP Requirements
address@hidden LDAP Requirements
address@hidden LDAP Configuration
address@hidden LDAP Configuration
 
-LDAP support is added by means of @file{ldap.el}, which is part of Emacs.
address@hidden needs an external command line utility named
address@hidden, available as part of Open LDAP
-(@url{http://www.openldap.org/}).
+LDAP support is added by means of @file{ldap.el}, which is part of
+Emacs.  @file{ldap.el} needs an external command line utility named
address@hidden, available as part of OpenLDAP
+(@url{http://www.openldap.org/}).  The configurations in this section
+were tested with OpenLDAP 2.4.23.
 
+The following examples use a base of
address@hidden,dc=example,dc=com} and the host name
address@hidden, a server that supports LDAP-over-SSL
+(the @code{ldaps} protocol, with default port @code{636}) and which
+requires authentication by the user @code{emacsuser} with password
address@hidden
+
+These configurations are meant to be self-contained; that is, each
+provides everything required for sensible TAB-completion of email
+fields.  BBDB lookups are attempted first; if a matching BBDB entry is
+found then EUDC will not attempt any LDAP lookups.
+
+Wildcard LDAP lookups are supported using the @code{*} character.  For
+example, attempting to TAB-complete the following:
+
address@hidden
+To: * Smith
address@hidden example
+
+will return all LDAP entries with surnames that begin with
address@hidden  In every LDAP query it makes, EUDC implicitly appends
+the wildcard character to the end of the last word.
+
address@hidden Emacs-only Configuration
+
+Emacs can pass most required configuration options via the
address@hidden command-line.  One exception is certificate
+configuration for LDAP-over-SSL, which must be specified in
address@hidden/etc/openldap/ldap.conf}.  On systems that provide such
+certificates as part of the @code{OpenLDAP} installation, this can be
+as simple as one line:
+
address@hidden
+TLS_CACERTDIR /etc/openldap/certs
address@hidden example
+
+In @file{.emacs}, these expressions suffice to configure EUDC for
+LDAP:
+
address@hidden
+(eval-after-load "message"
+  '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
+(customize-set-variable 'eudc-server-hotlist
+                        '(("" . bbdb)
+                          ("ldaps://directory.example.com" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist
+                        '(("ldaps://directory.example.com"
+                           base "ou=people,dc=example,dc=com"
+                           binddn "example\\emacsuser"
+                           passwd ldap-password-read)))
address@hidden lisp
+
+Specifying the function @code{ldap-password-read} for @code{passwd}
+will cause Emacs to prompt interactively for the password.  The
+password will then be validated and cached, unless
address@hidden is nil.  You can customize
address@hidden to control the duration for which the
+password is cached.  If you want to clear the cache, call
address@hidden
+
address@hidden External Configuration
+
+Your system may already be configured for a default LDAP server.  For
+example, @file{/etc/openldap/ldap.conf} might contain:
+
address@hidden
+BASE ou=people,dc=example,dc=com
+URI ldaps://directory.example.com
+TLS_CACERTDIR /etc/openldap/certs
address@hidden example
+
+To authenticate, the @dfn{bind distinguished name (binddn)} is
+required, in this case, @code{example\emacsuser}, along with the
+password.  These can be specified in @file{~/.authinfo.gpg} with the
+following line:
+
address@hidden
+machine ldaps://directory.example.com binddn example\emacsuser password s3cr3t
address@hidden example
+
+Then in the @file{.emacs} init file, these expressions suffice to
+configure EUDC for LDAP:
+
address@hidden
+(eval-after-load "message"
+  '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
+(customize-set-variable 'eudc-server-hotlist
+                        '(("" . bbdb)
+                          ("ldaps://directory.example.com" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist
+                        '(("ldaps://directory.example.com"
+                           auth-source t)))
address@hidden lisp
+
+For this example where we only care about one server, the server name
+can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which
+case @file{ldapsearch} defaults to the host name in
address@hidden/etc/openldap/ldap.conf}.
+
+The @file{~/.authinfo.gpg} line becomes:
+
address@hidden
+binddn example\emacsuser password s3cr3t
address@hidden example
+
+and the @file{.emacs} expressions become:
+
address@hidden
+(eval-after-load "message"
+  '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
+(customize-set-variable 'eudc-server-hotlist '(("" . bbdb) ("" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t)))
address@hidden lisp
 
 @node Usage
 @chapter Usage