2 '\" Copyright (c) 1998 NeoSoft, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH ldap n "" Ldap "Ldap Tcl Extension"
10 '\" Note: do not modify the .SH NAME line immediately below!
12 ldap \- connect to and query an LDAP server
14 \fBldap \fBopen \fR \fIcommand\fR \fIhostlist\fR
16 \fBldap \fBinit \fR \fIcommand\fR \fIhostlist\fR
18 \fBldap \fBexplode ?-nonames|-list?\fR \fIdn\fR
20 \fIcommand \fBsubcommand \fIoptions ...\fR
25 A new command by the name of \fIcommand\fR will be created to access
26 the LDAP database at \fIhostlist\fR. \fIhostlist\fR may contain elements
27 of the format \fBhost:port\fR if a port other than the default LDAP port
28 of 389 is required. The LDAP library will attempt to connect to each
29 host in turn until it succeeds or exhausts the list.
31 The \fBexplode\fR form provides a means (via ldap_explode(3)) to explode a DN
32 into its component parts. \fB-nonames\fR strips off the attribute names,
33 and -list returns a list suitable for \fBarray set\fR.
35 Finally, the last form, described in more detail below, refers genericly
36 to how the command created by the first two examples is used.
39 The Lightweight Directory Access Protocol provides TCP/IP access to
40 X.500 directory services and/or to a stand-alone LDAP server.
42 This code provides a Tcl interface to the
43 Lightweight Directory Access Protocol package using the Netscape
44 Software Development Kit. It can also be used with the freely
45 redistributable University of
46 Michigan (http://www.umich.edu/~rsug/ldap) version by defining the
47 UMICH_LDAP macro during compilation.
49 .SH CONNECTING TO AN LDAP SERVER
51 To create an ldap interface entity, we use the "ldap" command.
53 ldap open foo foo.bar.com
55 This opens a connection to a LDAP server on foo.bar.com, and makes
56 a new Tcl command, foo, through which we will manipulate the interface
57 and make queries to the remote LDAP server.
59 ldap init foo foo.bar.com
61 Same as above, foo is created, but for "init", opening the connection is
62 deferred until we actually try to do something.
64 For the purposes of this example, we're going to assume that "foo" is the
65 command created by opening a connection using "ldap open".
69 After a connection is made to an LDAP server, an LDAP bind operation must
70 be performed before other operations can be attempted over the connection.
72 Both simple authentication and kerberos authentication are available.
73 LDAP version 3 supports many new "SSL"-style authentication and encryption
74 systems, which are not currently supported by the OpenLDAP v1.2 server, and
75 hence by this interface package.
77 Currently simple and kerberos-based authentication, are supported.
79 To use LDAP and still have reasonable security in a networked,
80 Internet/Intranet environment, secure shell can be used to setup
81 secure, encrypted connections between client machines and the LDAP
82 server, and between the LDAP server and any replica or slave servers
85 To perform the LDAP "bind" operation:
87 foo bind simple dn password
89 foo bind kerberos_ldap
91 foo bind kerberos_both
93 It either returns nothing (success), or a Tcl error with appropriate error
98 foo bind simple "cn=Manager,o=NeoSoft Inc,c=us" "secret"
100 If you attempt to bind with one of the kerberos authentication types
101 described above and your LDAP library was not built with KERBEROS
102 defined, you will get an unknown auth type error.
104 To unbind an LDAP connection previously bound with "bind":
108 Note that unbinding also deletes the command (\fBfoo\fR in this case).
109 Deleting the command has the same affect.
111 The ability of the library to callback to the client, enabling re-binding
112 while following referrals, is not currently supported.
116 To delete an object in the LDAP database, use
120 To rename an object to another relative distinguished name, use
122 foo rename_rdn dn rdn
124 To rename an object to another relative distinguished name, leaving
125 the old entry as some kind of attribute (FIX: not sure if this is
126 right or how it works)
128 foo modify_rdn dn rdn
131 .SH ADDING NEW OBJECTS
133 foo add dn attributePairList
135 This creates a new distinguished name and defines zero or more attributes.
137 "attributePairList" is a list of key-value pairs, the same as would
138 be returned by "array get" if an array had been set up containing the
141 foo add "cn=karl, ou=People, o=NeoSoft Inc, c=US" {cn karl ...}
143 Some directory servers and/or their client SDKs will automatically
144 add the leaf attribute value for you.
146 Here is a more precise description of how an attributePairList looks:
148 {cn {karl {Karl Lehenbauer}} telephone 713-968-5800}
150 Note here that two cn values, "karl" and "Karl Lehenbauer", are added.
151 Is it an error to write:
153 {cn {Karl Lehenbauer}}
155 Which adds two cn values, "Karl" and "Lehenbauer", when the intention
156 was to give a single cn value of "Karl Lehenbauer". In real life, one
157 finds oneself making prodigous use of the \fBlist\fR command rather than
158 typing hard-coded lists.
160 We have noticed that the Netscape server will automatically add the
161 left-most rdn portion of the DN (ie. cn=karl), whereas the University
162 of Michigan and OpenLDAP 1.2 versions do not.
164 .SH ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES
166 You can have multiple values for a given attribute in an LDAP object.
167 These are represented in search results, through the Tcl interface,
170 foo add_attributes dn attributePairList
172 This adds key-value pairs to an existing DN. If an attribute being
173 added already exists, the new value will be appended to the list.
174 If a particular value being added to an attribute already exists in
175 the object a Tcl error is raised.
177 foo replace_attributes dn attributePairList
179 This replaces the specified attributes in an existing DN, leaving
180 unnamed ones untouched. Any previous values for the supplied attributes
181 (if any) are discarded.
183 foo delete_attributes dn attributePairList
185 This deletes attributes in the list. If an attribute "foo" has the
186 value list {bar snap}, and you delete using the attributePairList "foo bar",
187 "foo" will still have "snap".
189 If you provide an empty string ("") for the value list,
190 the entire attribute will be deleted.
194 The Tcl interface to searching takes a control array, which contains
195 a couple of mandatory key-value pairs, and can contain a number of
196 optional key-value pairs as well, for controlling the search, a
197 destination array, into which the specified attributes (or all attributes
198 of matching DNs if none are specified) and values are stored.
200 The "code" part is executed repeatedly, once for each DN matching the
203 foo search controlArray destArray code
205 Using data in the control array, a search is performed of the
206 LDAP server opened when foo was created. Possible elements
207 of the control array are enumerated blow.
209 controlArray(base) is the DN being searched from. (required)
211 controlArray(filter) contains the search criteria. (required)
213 controlArray(scope) must be "base", "one_level", or "subtree".
214 If not specified, scope defaults to "subtree".
216 controlArray(deref) must be "never", "search", "find", or "always"
217 If not specified, deref defaults to "never"
219 controlArray(attributes) is a list of attributes to be fetched.
220 If not specified, all attributes are fetched.
222 controlArray(timeout) a timeout value in seconds (may contain
223 fractional values -- extremely very small values are useful
224 for forcing timeout conditions to test timeouts).
226 For each matching record, destArray is populated with none,
227 some or all attribute-value pairs.
229 Note: There are some additional parameters that can be set, such as
230 how long the synchronous version of the routines should wait before
231 timing out, the interfaces for which are not available in the current
234 .SH CACHING (Note: Netscape clients do not have caching interfaces).
236 The UMich and OpenLDAP client libraries offers the client application fairly
237 fine-grained control of caching of results retrieved from searches,
238 offering significant performance improvement and reduced
241 By default, the cache is disabled.
243 To enable caching of data received from an LDAP connection,
245 foo cache enable timeout maxmem
247 ...where timeout is specified in seconds, and maxmem is the
248 maximum memory to be used for caching, in bytes.
250 If maxmem is 0, the cache size is restricted only by the timeout.
254 ...temporarily inhibits use of the cache (while disabled, new requests
255 are not cached and the cache is not checked when returning results).
257 Disabling the cache does not delete its contents.
261 ...turns off caching and completely removes the cache from memory.
265 ...deletes the entire cache contents, but does not affect
266 whether or not the cache is being used.
270 ...removes from the cache all request results that make reference
273 This should be used, for example, after doing an add_attributes,
274 delete_attributes, or replace_attributes (ldap_modify(3))
275 involving the requested DN. Generally this should not be needed,
276 as the Tcl interface automatically performs this operation on
277 any dn that is modified (add,replace,delete) while caching is
282 ...suppresses caching of any requests that result in an error.
284 foo cache size_errors
286 ...suppresses caching of any requests that result in an error,
287 except for requests resulting in "sizelimit exceeded", which
288 are cached. This is the default.
292 ...enables caching of all requests, including those that result
295 .SH IMPLEMENTATION DECISIONS
297 Because we used the new "Tcl object" C interfaces, this package only works
298 with Tcl 8.0 or above.
300 This package interfaces with the University of Michigan LDAP protocol
301 package, version 3.3, and OpenLDAP version 1.2, both of which are
302 implementations of version 2 of the LDAP protocol.
304 Although an LDAP client (or server) could be written in native Tcl 8.0,
305 as Tcl 8.0 and above can do binary I/O, and Tcl 8 and above have strings
306 that are fully eight-bit clean, for a first implementation, to minimize
307 compatibility problems, we created a C interface to the UMich LDAP library.
309 A native Tcl implementation would be cool because we could bring the receiving
310 of messages into the normal Tcl event loop and run the LDAP interface fully
313 This implementation is blocking, and blocking only. That is to say that
314 the Tcl event loop is frozen while the ldap routines are waiting on data.
316 This could be fixed either by recoding all of the I/O in the LDAP library
317 to use Tcl's I/O system instead, or by simply coding the LDAP interface in
318 native Tcl, as mentioned above.
320 Another advantage of coding in high-level Tcl, of course, is that the
321 client would immediately be cross-platform to Windows and the Mac, as
324 Binary data is not currently supported. It will probably be trivial to
325 add, we just haven't dug into it yet.
328 .SH FOR MORE INFORMATION
330 This document principally describes how to use our Tcl interface to the
333 For more information on LDAP and the University of Michigan LDAP package,
334 please visit the website mentioned above. The package includes substantial
335 documentation in the form of UNIX manual pages, a SLAPD/SLURPD guide
336 in Adobe Portable Document Format (pdf), and a number of Internet RFCs
337 related to LDAP services.
340 It was written by Karl Lehenbauer, of NeoSoft, Inc., in August and
341 September of 1997. Ldap explode, and numerous bug fixes and extensions
342 by Randy Kunkee, also of NeoSoft, Inc., in 1998-1999.
345 element, join, list, separator
347 The \fBldap init\fR syntax fails to return anything useful. Use
348 \fBldap open\fR instead.
350 \fBPackage require Ldaptcl\fR won't work unless the ldap and lber libraries
351 are also shared, and ldaptcl.so is itself created with the correct flags
352 (eg. -R for Solaris). In short there's a lot of details to make this part
353 work, but it should work out of the box for Solaris. Other systems may
354 require that LD_LIBRARY_PATH or other appropraite environment variables
355 be set at build and/or runtime.
357 An asynchronous interface should be provided with callbacks.
359 We have never tested Kerberos authentication.
361 It does not tolerate some illegal operations very well.
363 It is possible to create empty attributes, ie. attributes which are present
364 but have no value. This is done by deleting the attribute values rather
365 than, eg. "foo delete_attributes dn {telephone {}}" which would delete
366 the telephone attribute altogether. A search for presence of the attribute
367 may return an object, and yet it may have no value. This interface presents
368 such an object as not having the attribute at all (ie. you cannot tell).
369 The Netscape SDK does this for you, so this makes the behavior consistent
370 when using UMICH_LDAP.
372 \--enable-netscape configuration support has not been tested and probably