'\" '\" Copyright (c) 1998 NeoSoft, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros .TH ldap n "" Ldap "Ldap Tcl Extension" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME ldap \- connect to and query an LDAP server .SH SYNOPSIS \fBldap \fBopen \fR \fIcommand\fR \fIhostlist\fR .br \fBldap \fBinit \fR \fIcommand\fR \fIhostlist\fR ?protocol_version [2|3]? .br \fBldap \fBexplode ?-nonames|-list?\fR \fIdn\fR .br \fIcommand \fBsubcommand \fIoptions ...\fR .BE .SH OVERVIEW .PP A new command by the name of \fIcommand\fR will be created to access the LDAP database at \fIhostlist\fR. \fIhostlist\fR may contain elements of the format \fBhost:port\fR if a port other than the default LDAP port of 389 is required. The LDAP library will attempt to connect to each host in turn until it succeeds or exhausts the list. .PP The \fBexplode\fR form provides a means (via ldap_explode(3)) to explode a DN into its component parts. \fB-nonames\fR strips off the attribute names, and -list returns a list suitable for \fBarray set\fR. .PP Finally, the last form, described in more detail below, refers genericly to how the command created by the first two examples is used. .SH DESCRIPTION The Lightweight Directory Access Protocol provides TCP/IP access 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) version by defining the UMICH_LDAP macro during compilation. .SH CONNECTING TO AN LDAP SERVER To create an ldap interface entity, we use the "ldap" command. ldap open 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 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 for the connection. Currently, the only useful option is \fBprotocol_version\fR 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 open". .SH BINDING After a connection is made to an LDAP server, an LDAP bind operation must be performed before other operations can be attempted over the connection. Both simple authentication and kerberos authentication are available. LDAP version 3 supports many new "SSL"-style authentication and encryption 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 a networked, Internet/Intranet environment, secure shell can be used to setup 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" operation: foo bind simple dn password foo bind kerberos_ldap foo bind kerberos_dsa foo bind kerberos_both It either returns nothing (success), or a Tcl error with appropriate error text. For example, foo bind simple "cn=Manager,o=NeoSoft Inc,c=us" "secret" If you attempt to bind 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": foo unbind Note that unbinding also deletes the command (\fBfoo\fR in this case). Deleting the command has the same affect. The ability of the library to callback to the client, enabling re-binding while following referrals, is not currently supported. .SH DELETING OBJECTS To delete an object in the LDAP database, use foo delete dn To rename an object to another relative distinguished name, use foo rename_rdn dn rdn To rename an object to another relative distinguished name, leaving the old entry as some kind of attribute (FIX: not sure if this is right or how it works) foo modify_rdn dn rdn .SH 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 an array had been set 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 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 \fBlist\fR command rather than typing 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. .SH ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES You can have multiple values for a given attribute in an LDAP object. These are represented in 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 the object a Tcl error is raised. foo replace_attributes dn attributePairList This replaces the specified attributes in an existing DN, leaving unnamed ones untouched. Any previous values for the supplied attributes (if any) are discarded. foo delete_attributes dn attributePairList This deletes attributes in 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 ("") for the value list, the entire attribute will be deleted. In Ldaptcl version 2.0, multiple operations may be combined into a single transaction, ie. as in: foo add_attributes dn attributePairList replace attributePairList \ delete attributePairList .SH 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 destination array, into which the specified attributes (or all attributes of matching DNs if none are specified) and values are stored. The "code" part is executed repeatedly, once for each DN matching the search criteria. .nf foo search controlArray destArray code Using data in 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) 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) a timeout value in seconds (may contain fractional values -- extremely very small values are useful for forcing timeout conditions to test timeouts). .fi For each matching record, destArray is populated with none, some or all attribute-value pairs as determined by the request and access control lists on the server. Note: There are some additional parameters that can be set, such as how long the synchronous version of the routines should wait before timing out, the interfaces for which are not available in the current version. .SH COMPARE foo compare dn attribute value Interface to the ldap_compare_s() command. Compares the value of \fIattribute\fR in the object at \fIdn\fR to the \fIvalue\fR given in the command line. Returns an error if \fIdn\fR does not exist. Otherwise, a .SH 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 network traffic. By default, the cache is disabled. To enable caching of data received from an LDAP connection, foo cache enable timeout maxmem ...where timeout is specified in seconds, and maxmem is the maximum memory to be used for caching, in 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 returning 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 ...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 an error. foo cache size_errors ...suppresses caching of any requests that result in an error, except for requests resulting in "sizelimit exceeded", which are cached. This is the default. foo cache all_errors ...enables caching of all requests, including those that result in errors. .SH 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 3.3, and OpenLDAP version 1.2, both of which are implementations of version 2 of the LDAP protocol. Although an LDAP client (or server) could be written in 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 routines are waiting on data. This could be fixed either by recoding all of the I/O in the LDAP library to use Tcl's I/O system instead, or by simply coding the LDAP interface in native Tcl, as mentioned above. Another advantage of coding in 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. .SH 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 package, please visit the website mentioned above. The package includes substantial documentation in the form of UNIX manual pages, a SLAPD/SLURPD guide in Adobe Portable Document Format (pdf), and a number of Internet RFCs related to LDAP services. .SH AUTHORS It was written by Karl Lehenbauer, of NeoSoft, Inc., in August and September of 1997. Ldap explode, and numerous bug fixes and extensions by Randy Kunkee, also of NeoSoft, Inc., in 1998-1999. .SH KEYWORDS element, join, list, separator .SH BUGS The \fBldap init\fR syntax fails to return anything useful. Use \fBldap open\fR instead. \fBPackage require Ldaptcl\fR won't work unless the ldap 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 environment variables be set 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 values 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 probably has bugs.