X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/88bc8332eb14bcc4780fd3fe3dd4de2205c31dbf..91917dd58ec5278e555b9c693a830749083e8f89:/doc/misc/eudc.texi diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index b5a4e3aae4..8d59e97b44 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -2,16 +2,17 @@ @c %**start of header @setfilename ../../info/eudc.info @settitle Emacs Unified Directory Client (EUDC) Manual +@include docstyle.texi @afourpaper -@documentencoding UTF-8 +@syncodeindex fn cp +@syncodeindex vr cp @c %**end of header @copying -This file documents EUDC v1.30b. +This file documents EUDC version 1.40.0. EUDC is the Emacs Unified Directory Client, a common interface to -directory servers using various protocols such as LDAP or the CCSO white -pages directory system (PH/QI) +directory servers and contact information. Copyright @copyright{} 1998, 2000--2015 Free Software Foundation, Inc. @@ -30,7 +31,7 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* EUDC: (eudc). Emacs client for directory servers (LDAP, PH). +* EUDC: (eudc). Emacs client for directory servers (LDAP, BBDB). @end direntry @footnotestyle end @@ -39,7 +40,7 @@ modify this GNU manual.'' @title EUDC Manual @subtitle The Emacs Unified Directory Client @author by Oscar Figueiredo -@code{1.30b} +@code{1.40.0} @page @vskip 0pt plus 1fill @@ -61,8 +62,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 @@ -82,8 +82,6 @@ Currently supported back-ends are: @item LDAP, Lightweight Directory Access Protocol @item -CCSO PH/QI -@item BBDB, Big Brother's Insidious Database @end itemize @@ -108,7 +106,6 @@ Interface to BBDB to let you insert server records into your own BBDB database @menu * LDAP:: What is LDAP ? -* CCSO PH/QI:: What is CCSO, PH, QI ? * BBDB:: What is BBDB ? @end menu @@ -137,31 +134,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}) - - -@node CCSO PH/QI -@section CCSO PH/QI - -The Central Computing Services Office (CCSO) of the University of -Illinois at Urbana Champaign created and freely distributed a -directory system that was used by many organizations in the 1990s. -The system records information about people such as their address, -phone number, email, academic information or any other details it was -configured to. Nowadays this system is not widely used. - -The system consists of two parts: a database server traditionally called -@samp{qi} and a command-line client called @samp{ph}. -@ignore -Until 2010, the code could be downloaded from -@url{http://www-dev.cites.uiuc.edu/ph/}. -@end ignore - -The original command-line @samp{ph} client that came with the -@samp{ph/qi} distribution provided additional features that are -not implemented in EUDC, like the possibility to communicate with the -server in login-mode, which made it possible to change records in the -database. +(@pxref{LDAP Configuration}) @node BBDB @@ -174,14 +147,14 @@ and news readers. It is often used as an enhanced email address book. -EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an +EUDC considers BBDB as a directory server back end just like LDAP, +though BBDB has no client/server protocol and thus always resides +locally on your machine. The point in this is not to offer an alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. +more flexible ways to do that), but rather to offer an interface to +your local directory that is consistent with the interface to external +LDAP directories. This is particularly interesting when performing +queries on multiple servers. EUDC also offers a means to insert results from directory queries into your own local BBDB (@pxref{Creating BBDB Records}) @@ -213,17 +186,200 @@ 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 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 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. + +Most servers use LDAP-over-SSL these days; the examples here reflect +that. The other possibilities are: + +@vindex ldap-host-parameters-alist +@vindex ldap-ldapsearch-args +@itemize @bullet + +@item +Servers that do not require authentication or that do not encrypt +authentication traffic. + +Include @code{auth simple} in @code{ldap-host-parameters-alist}, which +causes the @code{-x} option to be passed to @command{ldapsearch}. + +@item +Servers that require SASL authentication. + +Pass any required extra options to @command{ldapsearch} using +@code{ldap-ldapsearch-args}. +@end itemize + +The following examples use a base of +@code{ou=people,dc=gnu,dc=org} and the host name +@code{ldap.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}. + +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} +* Troubleshooting:: Debug @command{ldapsearch} failures @end menu -@node LDAP Requirements -@section LDAP Requirements +@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: -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/}). +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + base "ou=people,dc=gnu,dc=org" + binddn "gnu\\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=gnu,dc=org +URI ldaps://ldap.gnu.org +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{gnu\emacsuser}. These can be specified in +@file{~/.authinfo.gpg} with the following line: + +@example +machine ldaps://ldap.gnu.org binddn gnu\emacsuser password s3cr3t +@end example + +Then in the @file{.emacs} init file, these expressions suffice to +configure EUDC for LDAP: + +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://ldap.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 @command{ldapsearch} defaults to the host name in +@file{/etc/openldap/ldap.conf}. + +The @file{~/.authinfo.gpg} line becomes: + +@example +binddn gnu\emacsuser password s3cr3t +@end example + +@noindent +and the @file{.emacs} expressions become: + +@vindex message-mode-map +@findex eudc-expand-inline +@vindex eudc-server-hotlist +@vindex ldap-host-parameters-alist +@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 Troubleshooting +@subsection Troubleshooting + +If @command{ldapsearch} exits with an error, you'll see a message like +this in the @code{*Messages*} buffer (all on one line): +@example +ldap-search-internal: Failed ldapsearch invocation: + ldapsearch "-Hldaps://ldap.gnu.org" "-bou=people,dc=gnu,dc=org" + "-Dgnu\emacsuser" "-W" "-LL" "-tt" "(&(mail=name*))" + "givenname" "sn" "mail" +@end example + +The @command{ldapsearch} command is formatted such that it can be +copied and pasted into a terminal. Set the @command{ldapsearch} debug +level to 5 by appending @code{-d 5} to the command line. @node Usage @chapter Usage @@ -283,13 +439,13 @@ may be specified by appending a colon and a number to the name of the server. You will not need this unless your server runs on a port other than the default (which depends on the protocol). If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but +if you use the BBDB back end) then @samp{localhost} is a reasonable value but it will be ignored anyway. @end defvar @defvar eudc-protocol The directory protocol to use to query the server. Currently supported -protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. +protocols in this version of EUDC are @code{ldap} and @code{bbdb}. @end defvar @deffn Command eudc-set-server @@ -326,11 +482,8 @@ attributes are ignored. Default is @code{t}. Directory standards may authorize different instances of the same attribute in a record. For instance the record of a person may contain -several email fields containing different email addresses. When using -a QI directory server this is difficult to distinguish from attributes -having multi-line values such as the postal address that may contain a -line for the street and another one for the zip code and city name. In -both cases, EUDC will consider the attribute duplicated. +several email fields containing different email addresses, in which +case EUDC will consider the attribute duplicated. EUDC has several methods to deal with duplicated attributes. The available methods are: @@ -696,11 +849,11 @@ trying to perform an inline query. Possible values are: Only the current directory server is tried @item hotlist The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached +for the query or @code{eudc-max-servers-to-query} is reached @item server-then-hotlist The current server then the servers in the hotlist are tried in the order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. +@code{eudc-max-servers-to-query} is reached. This is the default. @end table @end defvar @@ -772,39 +925,6 @@ convenience functions to parse phones and addresses. @end table @end defvar -The default value of the PH-specific value of that variable is -@code{eudc-ph-bbdb-conversion-alist}: - -@lisp -((name . name) - (net . email) - (address . (eudc-bbdbify-address address "Address")) - (phone . ((eudc-bbdbify-phone phone "Phone") - (eudc-bbdbify-phone office_phone "Office Phone")))) -@end lisp - -This means that: - -@itemize @bullet -@item -the @code{name} field of the BBDB record gets its value -from the @code{name} attribute of the directory record -@item -the @code{net} field of the BBDB record gets its value -from the @code{email} attribute of the directory record -@item -the @code{address} field of the BBDB record is obtained by parsing the -@code{address} attribute of the directory record with the function -@code{eudc-bbdbify-address} -@item -two @code{phone} fields are created (when possible) in the BBDB record. -The first one has @cite{Phone} for location and its value is obtained by -parsing the @code{phone} attribute of the PH/QI record with the function -@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location -its value is obtained by parsing the @code{office_phone} attribute of the -PH/QI record with the function @code{eudc-bbdbify-phone}. -@end itemize - @defun eudc-bbdbify-phone phone location This is a convenience function provided for use in @code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector @@ -929,14 +1049,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