@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.
@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
@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
* 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
@item
LDAP, Lightweight Directory Access Protocol
@item
-CCSO PH/QI
-@item
BBDB, Big Brother's Insidious Database
@end itemize
@menu
* LDAP:: What is LDAP ?
-* CCSO PH/QI:: What is CCSO, PH, QI ?
* BBDB:: What is BBDB ?
@end menu
@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
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})
@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
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
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:
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
@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
@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