Seth Woolley's Man Viewer

Manual for ldap - man n ldap

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

ldap(3,5,n)(n)                       Ldap Tcl Extension                       ldap(3,5,n)(n)



NAME
       ldap(3,5,n) - connect to and query an LDAP server

SYNOPSIS
       ldap(3,5,n) open(2,3,n)  command hostlist
       ldap(3,5,n) init  command hostlist ?protocol_version [2|3]?
       ldap(3,5,n) explode ?-nonames|-list? dn
       command subcommand options ...


OVERVIEW
       A new command by the name of command will be created to access(2,5) the LDAP
       database at hostlist.  hostlist may  contain  elements  of  the  format
       host:port  if(3,n)  a  port  other  than  the  default  LDAP  port of 389 is
       required.  The LDAP library will attempt to connect  to  each  host(1,5)  in(1,8)
       turn until it succeeds or exhausts the list.

       The explode form provides a means (via ldap_explode(3)) to explode a DN
       into its component parts.  -nonames strips off the attribute names, and
       -list returns a list suitable for array set(7,n,1 builtins).

       Finally,  the  last form, described in(1,8) more detail below, refers gener-
       icly to how the command created by the first two examples is used.

DESCRIPTION
       The Lightweight Directory Access Protocol  provides  TCP/IP  access(2,5)  to
       X.500 directory services and/or to a stand-alone LDAP server.

       This  code provides a Tcl interface to the Lightweight Directory Access
       Protocol package using the Netscape Software Development Kit.   It  can
       also  be  used  with  the freely redistributable University of Michigan
       (http://www.umich.edu/~rsug/ldap(3,5,n)) version(1,3,5) by  defining  the  UMICH_LDAP
       macro during compilation.


CONNECTING TO AN LDAP SERVER
       To create an ldap(3,5,n) interface entity, we use the "ldap(3,5,n)" command.

           ldap(3,5,n) open(2,3,n) foo foo.bar.com

       This  opens  a  connection to a LDAP server on foo.bar.com, and makes a
       new Tcl command, foo, through which we will  manipulate  the  interface
       and make queries to the remote LDAP server.

           ldap(3,5,n) init foo foo.bar.com

       Same  as  above, foo is created, but for "init", opening the connection
       is deferred until we actually try to do something.

       The init command also allows some optional values to  be  set(7,n,1 builtins)  for  the
       connection.   Currently,  the  only  useful  option is protocol_version
       which take a single argument to specify to use LDAP protocol  2  or  3.
       This may be required when connecting to older LDAP server.

       For  the  purposes of this example, we're going to assume that "foo" is
       the command created by opening a connection using "ldap(3,5,n) open(2,3,n)".


BINDING
       After a connection is made to an LDAP server, an  LDAP  bind(2,n,1 builtins)  operation
       must  be  performed  before  other operations can be attempted over the
       connection.

       Both simple authentication and kerberos authentication  are  available.
       LDAP version(1,3,5) 3 supports many new "SSL"-style authentication and encryp-
       tion systems, which are not currently supported by  the  OpenLDAP  v1.2
       server, and hence by this interface package.

       Currently simple and kerberos-based authentication, are supported.

       To  use  LDAP and still have reasonable security in(1,8) a networked, Inter-
       net/Intranet environment, secure shell can be  used  to  setup(2,8)  secure,
       encrypted  connections between client machines and the LDAP server, and
       between the LDAP server and any replica or slave servers that might  be
       used.

       To perform the LDAP "bind(2,n,1 builtins)" operation:

           foo bind(2,n,1 builtins) simple dn password

           foo bind(2,n,1 builtins) kerberos_ldap
           foo bind(2,n,1 builtins) kerberos_dsa
           foo bind(2,n,1 builtins) kerberos_both

       It  either  returns  nothing (success), or a Tcl error(8,n) with appropriate
       error(8,n) text.

       For example,

           foo bind(2,n,1 builtins) simple "cn=Manager,o=NeoSoft Inc,c=us" "secret"

       If you attempt to bind(2,n,1 builtins) with one of the  kerberos  authentication  types
       described  above  and  your  LDAP  library  was not built with KERBEROS
       defined, you will get an unknown auth type error.

       To unbind an LDAP connection previously bound with "bind(2,n,1 builtins)":

           foo unbind

       Note that unbinding also  deletes  the  command  (foo  in(1,8)  this  case).
       Deleting the command has the same affect.

       The ability of the library to callback to the client, enabling re-bind-
       ing while following referrals, is not currently supported.


DELETING OBJECTS
       To delete an object in(1,8) the LDAP database, use

           foo delete dn

       To rename(1,2,n) an object to another relative distinguished name, use

           foo rename_rdn dn rdn

       To rename(1,2,n) an object to another relative distinguished name, leaving the
       old  entry as some kind of attribute (FIX: not sure if(3,n) this is right or
       how it works)

           foo modify_rdn dn rdn



ADDING NEW OBJECTS
           foo add dn attributePairList

       This creates  a  new  distinguished  name  and  defines  zero  or  more
       attributes.

       "attributePairList"  is a list of key-value pairs, the same as would be
       returned by "array get" if(3,n) an array had been set(7,n,1 builtins) up containing the key-
       value pairs.

           foo add "cn=karl, ou=People, o=NeoSoft Inc, c=US" {cn karl ...}

       Some  directory servers and/or their client SDKs will automatically add
       the leaf attribute value for you.

       Here is a more precise description of how an attributePairList looks:

           {cn {karl {Karl Lehenbauer}} telephone 713-968-5800}

       Note here that two cn values, "karl" and "Karl Lehenbauer", are  added.
       Is it an error(8,n) to write:

           {cn {Karl Lehenbauer}}

       Which  adds  two cn values, "Karl" and "Lehenbauer", when the intention
       was to give a single cn value of "Karl Lehenbauer".  In real life,  one
       finds oneself making prodigous use of the list command rather than typ-
       ing hard-coded lists.

       We have noticed that the Netscape server  will  automatically  add  the
       left-most  rdn  portion of the DN (ie. cn=karl), whereas the University
       of Michigan and OpenLDAP 1.2 versions do not.


ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES
       You can have multiple values for a given attribute in(1,8) an  LDAP  object.
       These  are represented in(1,8) search results, through the Tcl interface, as
       a list.

           foo add_attributes dn attributePairList

       This adds key-value pairs to an existing DN.   If  an  attribute  being
       added already exists, the new value will be appended to the list.  If a
       particular value being added to an  attribute  already  exists  in(1,8)  the
       object a Tcl error(8,n) is raised.

           foo replace_attributes dn attributePairList

       This  replaces  the  specified  attributes  in(1,8)  an existing DN, leaving
       unnamed  ones  untouched.   Any  previous  values  for   the   supplied
       attributes (if(3,n) any) are discarded.

           foo delete_attributes dn attributePairList

       This  deletes  attributes  in(1,8)  the list.  If an attribute "foo" has the
       value list {bar snap}, and you delete using the attributePairList  "foo
       bar", "foo" will still have "snap".

       If  you  provide  an  empty  string(3,n) ("") for the value list, the entire
       attribute will be deleted.

       In Ldaptcl version(1,3,5) 2.0, multiple operations may be combined into a sin-
       gle transaction, ie. as in:

           foo  add_attributes  dn attributePairList replace attributePairList
            delete attributePairList


SEARCHING
       The Tcl interface to searching takes a control array, which contains  a
       couple  of  mandatory  key-value  pairs,  and  can  contain a number of
       optional key-value pairs as well, for controlling the search, a  desti-
       nation array, into which the specified attributes (or all attributes of
       matching DNs if(3,n) none are specified) and values are stored.

       The "code" part is executed repeatedly, once for each DN  matching  the
       search criteria.

           foo search controlArray destArray code

            Using data in(1,8) the control array, a search is performed of the
            LDAP server opened when foo was created.  Possible elements
            of the control array are enumerated blow.

            controlArray(base) is the DN being searched from. (required)

            controlArray(filter(1,3x,3x curs_util)) contains the search criteria. (required)

            controlArray(scope) must be "base", "one_level", or "subtree".
                If not specified, scope defaults to "subtree".

            controlArray(deref) must be "never", "search", "find", or "always"
                If not specified, deref defaults to "never"

            controlArray(attributes) is a list of attributes to be fetched.
                If not specified, all attributes are fetched.

            controlArray(timeout(1,3x,3x cbreak)) a timeout(1,3x,3x cbreak) value in(1,8) seconds (may contain
                fractional values -- extremely very small values are useful
                for forcing timeout(1,3x,3x cbreak) conditions to test timeouts).

       For each matching record, destArray is populated with none, some or all
       attribute-value pairs as determined by the request and  access(2,5)  control
       lists on the server.

       Note:   There  are  some additional parameters that can be set(7,n,1 builtins), such as
       how long the synchronous version(1,3,5) of the  routines  should  wait  before
       timing  out,  the interfaces for which are not available in(1,8) the current
       version.


COMPARE
           foo compare dn attribute value

       Interface to the  ldap_compare_s()  command.   Compares  the  value  of
       attribute  in(1,8)  the object at dn to the value given in(1,8) the command line.
       Returns an error(8,n) if(3,n) dn does not exist.  Otherwise, a


CACHING (Note: Netscape clients do not have caching interfaces).
       The UMich and OpenLDAP client libraries offers the  client  application
       fairly  fine-grained  control  of  caching  of  results  retrieved from
       searches, offering significant performance improvement and reduced net-
       work traffic.

       By default, the cache is disabled.

       To enable caching of data received from an LDAP connection,

           foo cache enable timeout(1,3x,3x cbreak) maxmem

            ...where  timeout(1,3x,3x cbreak)  is  specified  in(1,8)  seconds,  and  maxmem is the
            maximum memory to be used for caching, in(1,8) bytes.

            If maxmem is 0, the cache size is restricted only by the  timeout.

           foo cache disable

            ...temporarily  inhibits  use  of  the  cache (while disabled, new
       requests      are not cached and the cache is not checked when  return-
       ing results).

            Disabling the cache does not delete its contents.

           foo cache destroy

            ...turns off caching and completely removes the cache from memory.

           foo cache flush(8,n)

            ...deletes  the  entire  cache  contents,  but  does  not   affect
            whether or not the cache is being used.

           foo cache uncache dn

            ...removes  from the cache all request results that make reference
            to the specified DN.

            This should be used, for example, after doing  an  add_attributes,
            delete_attributes,    or    replace_attributes    (ldap_modify(3))
            involving the requested DN.  Generally this should not be  needed,
            as  the  Tcl  interface  automatically  performs this operation on
            any dn that is  modified  (add,replace,delete)  while  caching  is
            enabled.

           foo cache no_errors

            ...suppresses caching of any requests that result in(1,8) an error.

           foo cache size_errors

            ...suppresses  caching  of  any  requests that result in(1,8) an error(8,n),
            except for  requests  resulting  in(1,8)  "sizelimit  exceeded",  which
            are cached.  This is the default.

           foo cache all_errors

               ...enables caching of all requests, including those that result
            in(1,8) errors.


IMPLEMENTATION DECISIONS
       Because we used the new "Tcl object" C interfaces,  this  package  only
       works with Tcl 8.0 or above.

       This  package  interfaces with the University of Michigan LDAP protocol
       package, version(1,3,5) 3.3, and OpenLDAP  version(1,3,5)  1.2,  both  of  which  are
       implementations of version(1,3,5) 2 of the LDAP protocol.

       Although an LDAP client (or server) could be written in(1,8) native Tcl 8.0,
       as Tcl 8.0 and above can do binary  I/O,  and  Tcl  8  and  above  have
       strings  that are fully eight-bit clean, for a first implementation, to
       minimize compatibility problems, we created a C interface to the  UMich
       LDAP library.

       A  native  Tcl  implementation would be cool because we could bring the
       receiving of messages into the normal Tcl event loop and run  the  LDAP
       interface fully asynchronous.

       This  implementation  is  blocking,  and blocking only.  That is to say
       that the Tcl event loop is frozen while the ldap(3,5,n) routines  are  waiting
       on data.

       This  could  be  fixed  either  by  recoding all of the I/O in(1,8) the LDAP
       library to use Tcl's I/O system instead, or by simply coding  the  LDAP
       interface in(1,8) native Tcl, as mentioned above.

       Another  advantage  of coding in(1,8) high-level Tcl, of course, is that the
       client would immediately be cross-platform to Windows and the  Mac,  as
       well as Unix.

       Binary data is not currently supported.  It will probably be trivial to
       add, we just haven't dug into it yet.



FOR MORE INFORMATION
       This document principally describes how to use our Tcl interface to the
       LDAP library works.

       For  more information on LDAP and the University of Michigan LDAP pack-
       age, please visit the website mentioned above.   The  package  includes
       substantial   documentation  in(1,8)  the  form  of  UNIX  manual  pages,  a
       SLAPD/SLURPD guide in(1,8) Adobe Portable Document Format (pdf), and a  num-
       ber of Internet RFCs related to LDAP services.


AUTHORS
       It  was  written  by  Karl  Lehenbauer, of NeoSoft, Inc., in(1,8) August and
       September of 1997.  Ldap explode, and numerous bug fixes and extensions
       by Randy Kunkee, also of NeoSoft, Inc., in(1,8) 1998-1999.


KEYWORDS
       element, join(1,n), list, separator

BUGS
       The  ldap(3,5,n)  init  syntax fails to return anything useful.  Use ldap(3,5,n) open(2,3,n)
       instead.

       Package require Ldaptcl won't work unless the ldap(3,5,n) and  lber  libraries
       are  also  shared,  and  ldaptcl.so  is itself created with the correct
       flags (eg. -R for Solaris).  In short there's a lot of details to  make
       this  part  work, but it should work out of the box for Solaris.  Other
       systems may require that LD_LIBRARY_PATH or other appropraite  environ-
       ment variables be set(7,n,1 builtins) at build and/or runtime.

       An asynchronous interface should be provided with callbacks.

       We have never tested Kerberos authentication.

       It does not tolerate some illegal operations very well.

       It  is  possible  to  create empty attributes, ie. attributes which are
       present but have no value.  This is done by deleting the attribute val-
       ues  rather  than,  eg. "foo delete_attributes dn {telephone {}}" which
       would delete the telephone attribute altogether.  A search for presence
       of  the  attribute  may return an object, and yet it may have no value.
       This interface presents such an object as not having the  attribute  at
       all (ie. you cannot tell).  The Netscape SDK does this for you, so this
       makes the behavior consistent when using UMICH_LDAP.

       --enable-netscape configuration support has not been tested and  proba-
       bly has bugs.



Ldap                                                                   ldap(3,5,n)(n)

References for this manual (incoming links)