bug#16322: Acknowledgement (24.3; [PATCH] Streamline EUDC LDAP configuration)

[Thomas Fitzsimmons <fitzsim@fitzsim.org>]

[-- Attachment #1: Type: text/plain, Size: 620 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thomas Fitzsimmons <fitzsim@fitzsim.org>
>> Cc: 16322@debbugs.gnu.org
>> Date: Thu, 13 Nov 2014 12:11:59 -0500
>> 
>> * eudc.texi (LDAP Configuration): Rename from LDAP Requirements
>> and provide configuration examples.
>
> A few comments about this part:

[...]

New branch at:

https://github.com/fitzsim/emacs/tree/streamline-eudc-configuration-3

Attached are the patches that address your comments, and make the new
@cindex concepts available in the index.  I wanted to keep the authinfo
configuration on one line so I shortened the example hostname.

Thanks,
Thomas

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-LDAP-configuration-section-of-EUDC-manual.patch --]
[-- Type: text/x-patch, Size: 6916 bytes --]

From 5f6d017443b1d3dce6d9c3b3f18a1b5eafc47abe Mon Sep 17 00:00:00 2001
From: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Date: Sat, 15 Nov 2014 14:44:40 -0500
Subject: [PATCH 1/2] 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 | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 147 insertions(+), 8 deletions(-)

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index fcf81b0..06cee60 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2014-11-15  Thomas Fitzsimmons  <fitzsim@fitzsim.org>
+
+	* eudc.texi (LDAP Configuration): Rename from LDAP Requirements
+	and provide configuration examples.
+
 2014-11-10  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
 	* eww.texi (Basics): Document `eww-readable'.
diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 086e741..2343c19 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -137,7 +137,7 @@ location, etc@enddots{} 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,151 @@ 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
 
-@node LDAP Requirements
-@section LDAP Requirements
+@node LDAP Configuration
+@section LDAP Configuration
 
-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
-@file{ldapsearch}, 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
+@command{ldapsearch}, 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
+@code{ou=people,dc=example,dc=com} and the host name
+@code{ds.example.com}, 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
+@code{s3cr3t}.
+
+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:
+
+@example
+To: * Smith
+@end example
+
+@noindent
+will return all LDAP entries with surnames that begin with
+@code{Smith}.  In every LDAP query it makes, EUDC implicitly appends
+the wildcard character to the end of the last word.
+
+@menu
+* Emacs-only Configuration::    Configure with @file{.emacs}
+* External Configuration::      Configure with @file{/etc/openldap/ldap.conf}
+@end menu
+
+@node Emacs-only Configuration
+@subsection Emacs-only Configuration
+
+Emacs can pass most required configuration options via the
+@command{ldapsearch} command-line.  One exception is certificate
+configuration for LDAP-over-SSL, which must be specified in
+@file{/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:
+
+@example
+TLS_CACERTDIR /etc/openldap/certs
+@end example
+
+In @file{.emacs}, these expressions suffice to configure EUDC for
+LDAP:
+
+@lisp
+(eval-after-load "message"
+  '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
+(customize-set-variable 'eudc-server-hotlist
+                        '(("" . bbdb)
+                          ("ldaps://ds.example.com" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist
+                        '(("ldaps://ds.example.com"
+                           base "ou=people,dc=example,dc=com"
+                           binddn "example\\emacsuser"
+                           passwd ldap-password-read)))
+@end lisp
+
+@findex ldap-password-read
+@vindex passwd
+@vindex password-cache
+@vindex password-cache-expiry
+@findex password-reset
+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
+@code{password-cache} is nil.  You can customize
+@code{password-cache-expiry} to control the duration for which the
+password is cached.  If you want to clear the cache, call
+@code{password-reset}.
+
+@node External Configuration
+@subsection External Configuration
+
+Your system may already be configured for a default LDAP server.  For
+example, @file{/etc/openldap/ldap.conf} might contain:
+
+@example
+BASE ou=people,dc=example,dc=com
+URI ldaps://ds.example.com
+TLS_CACERTDIR /etc/openldap/certs
+@end example
+
+@cindex bind distinguished name
+@cindex binddn
+Authentication requires a password, and a @dfn{bind distinguished name
+(binddn)} representing the user, in this case,
+@code{example\emacsuser}.  These can be specified in
+@file{~/.authinfo.gpg} with the following line:
+
+@example
+machine ldaps://ds.example.com binddn example\emacsuser password s3cr3t
+@end example
+
+Then in the @file{.emacs} init file, these expressions suffice to
+configure EUDC for LDAP:
+
+@lisp
+(eval-after-load "message"
+  '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline))
+(customize-set-variable 'eudc-server-hotlist
+                        '(("" . bbdb)
+                          ("ldaps://ds.example.com" . ldap)))
+(customize-set-variable 'ldap-host-parameters-alist
+                        '(("ldaps://ds.example.com"
+                           auth-source t)))
+@end 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 @command{ldapsearch} defaults to the host name in
+@file{/etc/openldap/ldap.conf}.
+
+The @file{~/.authinfo.gpg} line becomes:
+
+@example
+binddn example\emacsuser password s3cr3t
+@end example
+
+@noindent
+and the @file{.emacs} expressions become:
+
+@lisp
+(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)))
+@end lisp
 
 @node Usage
 @chapter Usage
-- 
1.8.1.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Combine-eudc.texi-indices.patch --]
[-- Type: text/x-patch, Size: 1792 bytes --]

From 709e0881c7c1f2a243d7c2252b5ef7f5fcb2457a Mon Sep 17 00:00:00 2001
From: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Date: Sat, 15 Nov 2014 14:50:32 -0500
Subject: [PATCH 2/2] Combine eudc.texi indices

* eudc.texi: Combine indices.
---
 doc/misc/ChangeLog |  4 ++++
 doc/misc/eudc.texi | 16 ++++++----------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 06cee60..e00497b 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,5 +1,9 @@
 2014-11-15  Thomas Fitzsimmons  <fitzsim@fitzsim.org>
 
+	* eudc.texi: Combine indices.
+
+2014-11-15  Thomas Fitzsimmons  <fitzsim@fitzsim.org>
+
 	* eudc.texi (LDAP Configuration): Rename from LDAP Requirements
 	and provide configuration examples.
 
diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 2343c19..6711a2c 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -4,6 +4,8 @@
 @settitle Emacs Unified Directory Client (EUDC) Manual
 @afourpaper
 @documentencoding UTF-8
+@syncodeindex fn cp
+@syncodeindex vr cp
 @c %**end of header
 
 @copying
@@ -61,8 +63,7 @@ modify this GNU manual.''
 * Usage::                       The various usage possibilities explained
 * Credits::                     Who's done what
 * GNU Free Documentation License:: The license for this documentation.
-* Command and Function Index::
-* Variables Index::
+* Index::
 @end menu
 
 
@@ -1063,14 +1064,9 @@ in testing and proofreading the code and docs of @file{ph.el}.
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
-@node Command and Function Index
-@unnumbered Command and Function Index
+@node Index
+@unnumbered Index
 
-@printindex fn
-
-@node Variables Index
-@unnumbered Variables Index
-
-@printindex vr
+@printindex cp
 
 @bye
-- 
1.8.1.4