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.
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".
67 Note: Karl is particularly dissatisfied with the syntax of this option,
68 so it is one of the most likely things to change in a subsequent release.
72 After a connection is made to an LDAP server, an LDAP bind operation must
73 be performed before other operations can be attempted over the connection.
75 Both simple authentication and kerberos authentication are available.
76 LDAP version 3 supports many new "SSL"-style authentication and encryption
77 systems, which are not currently supported by the UMich server, and hence
78 by this interface package.
80 Currently simple authentication, and kerberos-based authentication, are
83 To use LDAP and still have reasonable security in a networked,
84 Internet/Intranet environment, secure shell can be used to setup
85 secure, encrypted connections between client machines and the LDAP
86 server, and between the LDAP server and any replica or slave servers
89 To perform the LDAP "bind" operation:
91 foo bind simple dn password
93 foo bind kerberos_ldap
95 foo bind kerberos_both
97 It either returns nothing (success), or a Tcl error with appropriate error
102 foo bind simple "cn=Manager,o=NeoSoft Inc,c=us" "secret"
104 If you attempt to bind with one of the kerberos authentication types
105 described above and your LDAP library was not built with KERBEROS
106 defined, you will get an unknown auth type error.
108 To unbind an LDAP connection previously bound with "bind":
112 Note that unbinding also deletes the command (\fBfoo\fR in this case).
113 Deleting the command has the same affect.
115 The ability of the library to callback to the client, enabling re-binding
116 while following referrals, is not currently supported.
120 To delete an object in the LDAP database, use
124 To rename an object to another relative distinguished name, use
126 foo rename_rdn dn rdn
128 To rename an object to another relative distinguished name, leaving
129 the old entry as some kind of attribute (FIX: not sure if this is
130 right or how it works)
132 foo modify_rdn dn rdn
135 .SH ADDING NEW OBJECTS
137 foo add dn attributePairList
139 This creates a new distinguished name and defines zero or more attributes.
141 "attributePairList" is a list of key-value pairs, the same as would
142 be returned by "array get" if an array had been set up containing the
143 key-value pairs. Note that, right now, the sort of lowest-level pair
144 of the DN must also appear in the attributePairList, as in:
146 foo add "cn=karl, ou=People, o=NeoSoft Inc, c=US" {cn karl ...}
148 Here is a more precise description of how an attributePairList looks:
150 {cn {karl {Karl Lehenbauer}} telephone 713-968-5800}
152 Note here that two cn values, "karl" and "Karl Lehenbauer", are added.
153 A command error is to write
155 {cn {Karl Lehenbauer}}
157 Which adds two cn values, "Karl" and "Lehenbauer", when the intention
158 was to give a single cn value of "Karl Lehenbauer". In real life, one
159 finds oneself making prodigous use of the \fBlist\fR command rather than
160 typing hard-coded lists.
162 We have noticed that the Netscape server will automatically add the
163 left-most rdn portion of the DN (ie. cn=karl), whereas the University
164 of Michigan version does not.
166 .SH ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES
168 You can have multiple occurrences of the same attribute in a record.
169 These are represented in search results, through the Tcl interface,
172 foo add_attributes dn attributePairList
174 This adds key-value pairs to an existing DN. If an attribute being
175 added already exists, the new value will be appended to the list.
177 foo replace_attributes dn attributePairList
179 This replaces specified key-value pairs in an existing DN, leaving
180 unnamed ones untouched.
182 foo delete_attributes dn attributePairList
184 This deletes attributes in the list. If a pair is "foo {bar snap}" and
185 you delete "foo bar", "foo" will still have "snap".
187 If you provide an empty string ("") for the value part of the key-value
188 pair, the entire attribute will be deleted. To reiterate, if you provide
189 a non-empty string for the value part, only that value will be removed
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 LDAP library offers the client application fairly fine-
237 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.
279 ...suppresses caching of any requests that result in an error.
281 foo cache size_errors
283 ...suppresses caching of any requests that result in an error,
284 except for requests resulting in "sizelimit exceeded", which
285 are cached. This is the default.
289 ...enables caching of all requests, including those that result
292 .SH IMPLEMENTATION DECISIONS
294 Because we used the new "Tcl object" C interfaces, this package only works
295 with Tcl 8.0 or above.
297 This package interfaces with the University of Michigan LDAP protocol
298 package, version 3.3, an implementation of version 2 of the LDAP protocol.
300 Although an LDAP client (or server) could be written in native Tcl 8.0,
301 as Tcl 8.0 and above can do binary I/O, and Tcl 8 and above have strings
302 that are fully eight-bit clean, for a first implementation, to minimize
303 compatibility problems, we created a C interface to the UMich LDAP library.
305 A native Tcl implementation would be cool because we could bring the receiving
306 of messages into the normal Tcl event loop and run the LDAP interface fully
309 This implementation is blocking, and blocking only. That is to say that
310 the Tcl event loop is frozen while the ldap routines are waiting on data.
312 This could be fixed either by recoding all of the I/O in the LDAP library
313 to use Tcl's I/O system instead, or by simply coding the LDAP interface in
314 native Tcl, as mentioned above.
316 Another advantage of coding in high-level Tcl, of course, is that the
317 client would immediately be cross-platform to Windows and the Mac, as
320 Binary data is not currently supported. It will probably be trivial to
321 add, we just haven't dug into it yet.
324 .SH FOR MORE INFORMATION
326 This document principally describes how to use our Tcl interface to the
329 For more information on LDAP and the University of Michigan LDAP package,
330 please visit the website mentioned above. The package includes substantial
331 documentation in the form of UNIX manual pages, a SLAPD/SLURPD guide
332 in Adobe Portable Document Format (pdf), and a number of Internet RFCs
333 related to LDAP services.
336 It was written by Karl Lehenbauer, of NeoSoft, Inc., in August and
337 September of 1997. Ldap explode, and numerous bug fixes by Randy
338 Kunkee, also of NeoSoft, Inc., in 1998.
341 element, join, list, separator
343 The \fBldap init\fR syntax fails to return anything useful. Use
344 \fBldap open\fR instead.
346 \fBPackage require Ldaptcl\fR won't work unless the ldap and lber libraries
347 are also shared, and ldaptcl.so is itself created with the correct flags
348 (eg. -R for Solaris). In short there's a lot of details to make this part
349 work, but it should work out of the box for Solaris. Other systems may
350 require that LD_LIBRARY_PATH or other appropraite environment variables
351 be set at build and/or runtime.
353 An asynchronous interface should be provided with callbacks.
355 We have never tested Kerberos authentication.
357 It does not tolerate some illegal operations very well.
359 It is possible to create empty attributes, ie. attributes which are present
360 but have no value. This is done by deleting the attribute values rather
361 than, eg. "foo delete_attributes dn {telephone {}}" which would delete
362 the telephone attribute altogether. A search for presence of the attribute
363 may return an object, and yet it may have no value. This interface presents
364 such an object as not having the attribute at all (ie. you cannot tell).
365 The Netscape SDK does this for you, so this makes the behavior consistent
366 when using UMICH_LDAP.
368 \--enable-netscape configuration support has not been tested and probably