git.chise.org Git - chise/xemacs-chise.git.1/blob - man/lispref/ldap.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the XEmacs Lisp Reference Manual.
   3 @c Copyright (C) 1998 Free Software Foundation, Inc.
   4 @c See the file lispref.texi for copying conditions.
   5 @setfilename ../../info/ldap.info
   6 @node LDAP Support, PostgreSQL Support, ToolTalk Support, top
   7 @chapter LDAP Support
   8 @cindex LDAP
   9
  10 XEmacs can be linked with a LDAP client library to provide Elisp primitives
  11 to access directory servers using the Lightweight Directory Access Protocol.
  12
  13 @menu
  14 * Building XEmacs with LDAP support::  How to add LDAP support to XEmacs
  15 * XEmacs LDAP API::             Lisp access to LDAP functions
  16 * Syntax of Search Filters::    A brief summary of RFC 1558
  17 @end menu
  18
  19 @node Building XEmacs with LDAP support, XEmacs LDAP API, LDAP Support, LDAP Support
  20 @comment  node-name,  next,  previous,  up
  21 @section Building XEmacs with LDAP support
  22
  23 LDAP support must be added to XEmacs at build time since it requires
  24 linking to an external LDAP client library.  As of 21.2, XEmacs has been
  25 successfully built and tested with
  26
  27 @itemize @bullet
  28 @item OpenLDAP 1.0.3 (@url{http://www.openldap.org/})
  29 @item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
  30 @item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
  31 @end itemize
  32
  33 Other libraries conforming to RFC 1823 will probably work also but may
  34 require some minor tweaking at C level.
  35
  36 The standard XEmacs configure script autodetects an installed LDAP
  37 library provided the library itself and the corresponding header files
  38 can be found in the library and include paths.  A successful detection
  39 will be signalled in the final output of the configure script.
  40
  41
  42
  43 @node XEmacs LDAP API, Syntax of Search Filters, Building XEmacs with LDAP support, LDAP Support
  44 @comment  node-name,  next,  previous,  up
  45 @section XEmacs LDAP API
  46
  47 XEmacs LDAP API consists of two layers:  a low-level layer which tries
  48 to stay as close as possible to the C API (where practical) and a
  49 higher-level layer which provides more convenient primitives to
  50 effectively use LDAP.
  51
  52 As of XEmacs 21.0, only interfaces to basic LDAP search functions are
  53 provided, broader support is planned in future versions.
  54
  55 @menu
  56 * LDAP Variables::              Lisp variables related to LDAP
  57 * The High-Level LDAP API::     High-level LDAP lisp functions
  58 * The Low-Level LDAP API::      Low-level LDAP lisp primitives
  59 @end menu
  60
  61
  62 @node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
  63 @comment  node-name,  next,  previous,  up
  64 @subsection LDAP Variables
  65
  66 @defvar ldap-default-host
  67 The default LDAP server hostname.
  68 A TCP port number can be appended to that name using a colon as
  69 a separator.
  70 @end defvar
  71
  72 @defvar ldap-default-port
  73 Default TCP port for LDAP connections.
  74 Initialized from the LDAP library. Default value is 389.
  75 @end defvar
  76
  77 @defvar ldap-default-base
  78 Default base for LDAP searches.
  79 This is a string using the syntax of RFC 1779.
  80 For instance, "o¬ME, cÿ" limits the search to the
  81 Acme organization in the United States.
  82 @end defvar
  83
  84 @defvar ldap-host-parameters-alist
  85 An alist of per host options for LDAP transactions.
  86 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
  87 @var{host} is the name of an LDAP server. A TCP port number can be
  88 appended to that name using a colon as a separator.
  89 @var{propn} and @var{valn} are
  90 property/value pairs describing parameters for the server.  Valid
  91 properties:
  92 @table @code
  93 @item binddn
  94 The distinguished name of the user to bind as.  This may look like
  95 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
  96 @item passwd
  97 The password to use for authentication.
  98 @item auth
  99 The authentication method to use, possible values depend on the LDAP
 100 library XEmacs was compiled with, they may include @code{simple},
 101 @code{krbv41} and @code{krbv42}.
 102 @item base
 103 The base for the search. This may look like @samp{cÿ, o¬me}, see
 104 RFC 1779 for syntax details.
 105 @item scope
 106 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
 107 indicating the scope of the search limited to a base
 108 object, to a single level or to the whole subtree.
 109 @item deref
 110 The dereference policy is one of the symbols @code{never},
 111 @code{always}, @code{search} or @code{find} and defines how aliases are
 112 dereferenced.
 113 @table @code
 114 @item never
 115 Aliases are never dereferenced
 116 @item always
 117 Aliases are always dereferenced
 118 @item search
 119 Aliases are dereferenced when searching
 120 @item find
 121 Aliases are dereferenced when locating the base object for the search
 122 @end table
 123 @item timelimit
 124 The timeout limit for the connection in seconds.
 125 @item sizelimit
 126 The maximum number of matches to return for searches performed on this connection.
 127 @end table
 128 @end defvar
 129
 130
 131
 132 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
 133 @comment  node-name,  next,  previous,  up
 134 @subsection The High-Level LDAP API
 135
 136 As of this writing the high-level Lisp LDAP API only provides for LDAP
 137 searches.  Further support is planned in the future.
 138
 139 The @code{ldap-search} function provides the most convenient interface
 140 to perform LDAP searches.  It opens a connection to a host, performs the
 141 query and cleanly closes the connection thus insulating the user from
 142 all the details of the low-level interface such as LDAP Lisp objects
 143 @pxref{The Low-Level LDAP API}
 144
 145 @defun ldap-search filter &optional host attributes attrsonly
 146 Perform an LDAP search.
 147 @var{filter} is the search filter @pxref{Syntax of Search Filters}
 148 @var{host} is the LDAP host on which to perform the search
 149 @var{attributes} is the specific attributes to retrieve, @code{nil} means
 150 retrieve all
 151 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
 152 their associated values.
 153 Additional search parameters can be specified through
 154 @code{ldap-host-parameters-alist}.
 155 @end defun
 156
 157 @node The Low-Level LDAP API,  , The High-Level LDAP API, XEmacs LDAP API
 158 @comment  node-name,  next,  previous,  up
 159 @subsection The Low-Level LDAP API
 160
 161 @menu
 162 * The LDAP Lisp Object::
 163 * Opening and Closing a LDAP Connection::
 164 * Searching on a LDAP Server (Low-level)::
 165 @end menu
 166
 167 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
 168 @comment  node-name,  next,  previous,  up
 169 @subsubsection The LDAP Lisp Object
 170
 171 An internal built-in @code{ldap} lisp object represents a LDAP
 172 connection.
 173
 174 @defun ldapp object
 175 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
 176 @end defun
 177
 178 @defun ldap-host ldap
 179 Return the server host of the connection represented by @var{ldap}
 180 @end defun
 181
 182 @defun ldap-live-p ldap
 183 Return non-@code{nil} if @var{ldap} is an active LDAP connection
 184 @end defun
 185
 186
 187 @node Opening and Closing a LDAP Connection, Searching on a LDAP Server (Low-level), The LDAP Lisp Object, The Low-Level LDAP API
 188 @comment  node-name,  next,  previous,  up
 189 @subsubsection Opening and Closing a LDAP Connection
 190
 191 @defun ldap-open host &optional plist
 192 Open a LDAP connection to @var{host}.
 193 @var{plist} is a property list containing additional parameters for the connection.
 194 Valid keys in that list are:
 195 @table @code
 196 @item port
 197 The TCP port to use for the connection if different from
 198 @code{ldap-default-port} or the library builtin value
 199 @item auth
 200 The authentication method to use, possible values depend on the LDAP
 201 library XEmacs was compiled with, they may include @code{simple},
 202 @code{krbv41} and @code{krbv42}.
 203 @item binddn
 204 The distinguished name of the user to bind as.  This may look like
 205 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
 206 @item passwd
 207 The password to use for authentication.
 208 @item deref
 209 The dereference policy is one of the symbols @code{never},
 210 @code{always}, @code{search} or @code{find} and defines how aliases are
 211 dereferenced.
 212 @table @code
 213 @item never
 214 Aliases are never dereferenced
 215 @item always
 216 Aliases are always dereferenced
 217 @item search
 218 Aliases are dereferenced when searching
 219 @item find
 220 Aliases are dereferenced when locating the base object for the search
 221 @end table
 222 The default is @code{never}.
 223 @item timelimit
 224 The timeout limit for the connection in seconds.
 225 @item sizelimit
 226 The maximum number of matches to return for searches performed on this connection.
 227 @end table
 228 @end defun
 229
 230 @defun ldap-close ldap
 231 Close the connection represented by @var{ldap}
 232 @end defun
 233
 234
 235 @node Searching on a LDAP Server (Low-level),  , Opening and Closing a LDAP Connection, The Low-Level LDAP API
 236 @comment  node-name,  next,  previous,  up
 237 @subsubsection Searching on a LDAP Server (Low-level)
 238
 239 @code{ldap-search-internal} is the low-level primitive to perform a
 240 search on a LDAP server.  It works directly on an open LDAP connection
 241 thus requiring a preliminary call to @code{ldap-open}.  Multiple
 242 searches can be made on the same connection, then the session must be
 243 closed with @code{ldap-close}.
 244
 245
 246 @defun ldap-search-internal ldap filter base scope attrs attrsonly
 247 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
 248 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
 249 @var{base} is the distinguished name at which to start the search.
 250 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
 251 @code{subtree} indicating the scope of the search limited to a base
 252 object, to a single level or to the whole subtree.  The default is
 253 @code{subtree}.
 254 @code{attrs} is a list of strings indicating which attributes to retrieve
 255 for each matching entry. If @code{nil} all available attributes are returned.
 256 If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
 257 their associated values
 258 The function returns a list of matching entries.  Each entry being itself
 259 an alist of attribute/values.
 260 @end defun
 261
 262
 263
 264
 265
 266 @node Syntax of Search Filters,  , XEmacs LDAP API, LDAP Support
 267 @comment  node-name,  next,  previous,  up
 268 @section Syntax of Search Filters
 269
 270 LDAP search functions use RFC1558 syntax to describe the search filter.
 271 In that syntax simple filters have the form:
 272
 273 @example
 274 (<attr> <filtertype> <value>)
 275 @end example
 276
 277 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
 278 @code{o} for Organization, etc...
 279
 280 @code{<value>} is the corresponding value.  This is generally an exact
 281 string but may also contain @code{*} characters as wildcards
 282
 283 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
 284 respectively describe equality, approximate equality, inferiority and
 285 superiority.
 286
 287 Thus @code{(cn=John Smith)} matches all records having a canonical name
 288 equal to John Smith.
 289
 290 A special case is the presence filter @code{(<attr>=*} which matches
 291 records containing a particular attribute.  For instance @code{(mail=*)}
 292 matches all records containing a @code{mail} attribute.
 293
 294 Simple filters can be connected together with the logical operators
 295 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
 296 not operators.
 297
 298 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
 299 matches records of class @code{Person} containing a @code{mail}
 300 attribute and corresponding to people whose last name is @code{Smith} or
 301 whose first name is @code{John}.
 302
 303
 304