From c0984249eb65641a0876594183c80fd8e6b37962 Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons Date: Fri, 10 Apr 2015 21:55:40 -0400 Subject: [PATCH] Clean up LDAP Configuration section of EUDC manual * doc/misc/eudc.texi: Combine indices. (LDAP Configuration): Use command markup. Add index entries. Change formatting. Wrap long lines. Add noindent markup. --- doc/misc/eudc.texi | 70 +++++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 28 deletions(-) diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 9757c82fe7e..76a25c1a33e 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 @@ -220,15 +221,15 @@ email composition buffers (@pxref{Inline Query Expansion}) @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 OpenLDAP +Emacs. @file{ldap.el} needs an external program called +@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{directory.example.com}, a server that supports LDAP-over-SSL -(the @code{ldaps} protocol, with default port @code{636}) and which +@code{ldaps.gnu.org}, 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}. @@ -244,14 +245,21 @@ example, attempting to TAB-complete the following: 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 -@file{ldapsearch} command-line. One exception is certificate +@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 @@ -269,14 +277,19 @@ LDAP: '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) (customize-set-variable 'eudc-server-hotlist '(("" . bbdb) - ("ldaps://directory.example.com" . ldap))) + ("ldaps://ldaps.gnu.org" . ldap))) (customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://directory.example.com" + '(("ldaps://ldaps.gnu.org" 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 @@ -285,6 +298,7 @@ password will then be validated and cached, unless 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 @@ -292,17 +306,19 @@ example, @file{/etc/openldap/ldap.conf} might contain: @example BASE ou=people,dc=example,dc=com -URI ldaps://directory.example.com +URI ldaps://ldaps.gnu.org TLS_CACERTDIR /etc/openldap/certs @end 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: +@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://directory.example.com binddn example\emacsuser password s3cr3t +machine ldaps://ldaps.gnu.org binddn example\emacsuser password s3cr3t @end example Then in the @file{.emacs} init file, these expressions suffice to @@ -313,15 +329,15 @@ configure EUDC for LDAP: '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) (customize-set-variable 'eudc-server-hotlist '(("" . bbdb) - ("ldaps://directory.example.com" . ldap))) + ("ldaps://ldaps.gnu.org" . ldap))) (customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://directory.example.com" + '(("ldaps://ldaps.gnu.org" 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 @file{ldapsearch} defaults to the host name in +case @command{ldapsearch} defaults to the host name in @file{/etc/openldap/ldap.conf}. The @file{~/.authinfo.gpg} line becomes: @@ -330,13 +346,16 @@ The @file{~/.authinfo.gpg} line becomes: 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))) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) ("" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("" auth-source t))) @end lisp @node Usage @@ -1043,14 +1062,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 - -@printindex fn - -@node Variables Index -@unnumbered Variables Index +@node Index +@unnumbered Index -@printindex vr +@printindex cp @bye -- 2.39.2