[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master a6d4651 15/17: Update LDAP configuration section of
From: |
Stefan Monnier |
Subject: |
[Emacs-diffs] master a6d4651 15/17: Update LDAP configuration section of EUDC manual |
Date: |
Fri, 23 Jan 2015 22:20:36 +0000 |
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
- [Emacs-diffs] master b7d2dfa 06/17: Change eudc-expansion-overwrites-query default to nil, (continued)
- [Emacs-diffs] master b7d2dfa 06/17: Change eudc-expansion-overwrites-query default to nil, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 6a3a3b0 09/17: Downcase field names in LDAP results, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 87ff9ae 07/17: Add password-cache support to ldap.el, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master ea0ea90 08/17: ldap-search-internal: Send password to ldapsearch through a pipe, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 1e1f5b9 10/17: Append LDAP wildcard character to end of search string, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 81d0909 12/17: Restore former eudc-expand-inline settings after a nonlocal exit, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 7860227 11/17: Do not ask the user for an LDAP base if a default has been provided, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 9006ccd 13/17: Handle nil password-cache in ldap-password-read, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master 4a77d69 14/17: ldap-password-read: Validate password before caching it, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master e56e1b9 16/17: Mention binddn in LDAP credentials error message, Stefan Monnier, 2015/01/23
- [Emacs-diffs] master a6d4651 15/17: Update LDAP configuration section of EUDC manual,
Stefan Monnier <=
- [Emacs-diffs] master ac5475d 17/17: lisp/net/{eudc, ldap}: Merge branch streamline-eudc-configuration, Stefan Monnier, 2015/01/23