X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/81deba3d7a2b187d58fe26bd8b4eafb5687095e1..9c3dbabee3cc8cddce33aaa7622dfb4c11353123:/doc/misc/eudc.texi diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 9757c82fe7..da63975c2e 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -2,18 +2,19 @@ @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. +Copyright @copyright{} 1998, 2000--2016 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -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 @@ -140,30 +137,6 @@ EUDC requires external support to access LDAP directory servers (@pxref{LDAP Configuration}) -@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. - - @node BBDB @section 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}) @@ -220,15 +193,36 @@ 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. +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=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{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}. @@ -244,14 +238,22 @@ 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} +* Troubleshooting:: Debug @command{ldapsearch} failures +@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 @@ -264,19 +266,28 @@ TLS_CACERTDIR /etc/openldap/certs In @file{.emacs}, 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://directory.example.com" . ldap))) + ("ldaps://ldap.gnu.org" . ldap))) (customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://directory.example.com" - base "ou=people,dc=example,dc=com" - binddn "example\\emacsuser" + '(("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 @@ -285,60 +296,91 @@ 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 example, @file{/etc/openldap/ldap.conf} might contain: @example -BASE ou=people,dc=example,dc=com -URI ldaps://directory.example.com +BASE ou=people,dc=gnu,dc=org +URI ldaps://ldap.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{gnu\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://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://directory.example.com" . ldap))) + ("ldaps://ldap.gnu.org" . ldap))) (customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://directory.example.com" + '(("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 @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: @example -binddn example\emacsuser password s3cr3t +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))) +(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 @@ -397,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 @@ -440,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: @@ -810,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 @@ -886,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 @@ -1043,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