From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thomas Fitzsimmons Newsgroups: gmane.emacs.bugs Subject: bug#16322: Acknowledgement (24.3; [PATCH] Streamline EUDC LDAP configuration) Date: Sat, 15 Nov 2014 14:58:59 -0500 Message-ID: References: <83mw7vkvf1.fsf@gnu.org> <83ioiikgag.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1416081621 23573 80.91.229.3 (15 Nov 2014 20:00:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 15 Nov 2014 20:00:21 +0000 (UTC) Cc: 16322@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Nov 15 21:00:16 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XpjW3-0000X1-42 for geb-bug-gnu-emacs@m.gmane.org; Sat, 15 Nov 2014 21:00:15 +0100 Original-Received: from localhost ([::1]:41822 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XpjW2-0007Gx-RF for geb-bug-gnu-emacs@m.gmane.org; Sat, 15 Nov 2014 15:00:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50640) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XpjVw-0007FQ-LZ for bug-gnu-emacs@gnu.org; Sat, 15 Nov 2014 15:00:13 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XpjVs-0008Ky-1D for bug-gnu-emacs@gnu.org; Sat, 15 Nov 2014 15:00:08 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:36917) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XpjVr-0008KE-VC for bug-gnu-emacs@gnu.org; Sat, 15 Nov 2014 15:00:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1XpjVr-00086F-7O for bug-gnu-emacs@gnu.org; Sat, 15 Nov 2014 15:00:03 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Thomas Fitzsimmons Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 15 Nov 2014 20:00:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 16322 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 16322-submit@debbugs.gnu.org id=B16322.141608155031035 (code B ref 16322); Sat, 15 Nov 2014 20:00:03 +0000 Original-Received: (at 16322) by debbugs.gnu.org; 15 Nov 2014 19:59:10 +0000 Original-Received: from localhost ([127.0.0.1]:34130 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XpjUz-00084U-Sl for submit@debbugs.gnu.org; Sat, 15 Nov 2014 14:59:10 -0500 Original-Received: from mail-ig0-f171.google.com ([209.85.213.171]:65535) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1XpjUs-00084F-Vh for 16322@debbugs.gnu.org; Sat, 15 Nov 2014 14:59:07 -0500 Original-Received: by mail-ig0-f171.google.com with SMTP id uq10so1441164igb.10 for <16322@debbugs.gnu.org>; Sat, 15 Nov 2014 11:59:02 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-type; bh=yGB2SvUww89d7ZpcYW+wcNVRXu4MUd8NUGSt+41y6cs=; b=G1EE4al9zH1swmbtFrH0Kxrn29gO2xeuZFNtZSN786kKvh7pj+RBi5fofUyusV/fMD RGS291dFNYQMoiSzPXPjqV8x1kzg/dgKUsNqj7N2oVe0cko+SfIkJ+ImJIR39BVHmZfF aKKz+zg+wr/jQUR5TY+q8wpaNN8HguD0i41VN9e6vJINhq8KR+e2uQt7T3YoYykV40yL 5egIKKnuwb25gufjyukv4nBMJ03iGxv3gGDGXVIwSyow/0ptZt5D08flxlsIf1V+RH0O y8QY1CjNAyx7RJ3gGP9C2HyA8oDBFZYeqCpCUbNZP5Sm50Ui0AZA1zQqd80eD+pZFOVX jBfg== X-Gm-Message-State: ALoCoQk9D9qFGB7G/UOPF846rGU552I0FJasY1SHYSSlDmSAWs1Ke1qRgnk/o6i2DzI2sAOE1Dqe X-Received: by 10.107.35.13 with SMTP id j13mr11562746ioj.55.1416081542068; Sat, 15 Nov 2014 11:59:02 -0800 (PST) Original-Received: from hp-dv5t (69-165-165-189.dsl.teksavvy.com. [69.165.165.189]) by mx.google.com with ESMTPSA id p198sm1727678iop.36.2014.11.15.11.59.00 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Sat, 15 Nov 2014 11:59:00 -0800 (PST) In-Reply-To: <83ioiikgag.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 13 Nov 2014 22:16:07 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:96083 --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Thomas Fitzsimmons >> 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 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Update-LDAP-configuration-section-of-EUDC-manual.patch >From 5f6d017443b1d3dce6d9c3b3f18a1b5eafc47abe Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons 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 + + * eudc.texi (LDAP Configuration): Rename from LDAP Requirements + and provide configuration examples. + 2014-11-10 Lars Magne Ingebrigtsen * 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 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0002-Combine-eudc.texi-indices.patch >From 709e0881c7c1f2a243d7c2252b5ef7f5fcb2457a Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons 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 + * eudc.texi: Combine indices. + +2014-11-15 Thomas Fitzsimmons + * 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 --=-=-=--