1ldap(n) LDAP client ldap(n)
2______________________________________________________________________________
6
8 ldap - LDAP client
9
11 package require Tcl 8.4
12 package require ldap ?1.6.6?
14 ::ldap::connect host ?port?
16 ::ldap::secure_connect host ?port?
18 ::ldap::disconnect handle
20 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
22 ::ldap::bind handle ?name? ?password?
24 ::ldap::bindSASL handle ?name? ?password?
26 ::ldap::unbind handle
28 ::ldap::search handle baseObject filterString attributes ?-scope scope?
30 ::ldap::searchInit handle baseObject filterString attributes options
32 ::ldap::searchNext handle
34 ::ldap::searchEnd handle
36 ::ldap::searchInit
38 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
40 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
42 ValToAdd?
43 ::ldap::add handle dn attrValueTuples
45 ::ldap::addMulti handle dn attrValueTuples
47 ::ldap::delete handle dn
49 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
51 ::ldap::info ip handle
53 ::ldap::info bound handle
55 ::ldap::info bounduser handle
57 ::ldap::info connections
59 ::ldap::info tls handle
61 ::ldap::info saslmechanisms handle
63 ::ldap::info control handle
65 ::ldap::info extensions extensions
67 ::ldap::info whoami handle
69_________________________________________________________________
71
73 The ldap package provides a simple Tcl-only client library for the
74 LDAPv3 protocol as specified in RFC 2251 (http://www.rfc-edi‐
75 tor.org/rfc/rfc2251.txt). It works by opening the standard (or secure)
76 LDAP socket on the server, and then providing a Tcl API to access the
77 LDAP protocol commands. All server errors are returned as Tcl errors
78 (thrown) which must be caught with the Tcl catch command.
79
81 ::ldap::connect host ?port?
82 Opens a LDAPv3 connection to the specified host, at the given
83 port, and returns a token for the connection. This token is the
84 handle argument for all other commands. If no port is specified
85 it will default to 389.
86 The command blocks until the connection has been established, or
88 establishment definitely failed.
89 ::ldap::secure_connect host ?port?
91 Like ::ldap::connect, except that the created connection is
92 secured by SSL. The port defaults to 636. This command depends
93 on the availability of the package TLS, which is a SSL binding
94 for Tcl. If TLS is not available, then this command will fail.
95 The command blocks until the connection has been established, or
97 establishment definitely failed.
98 ::ldap::disconnect handle
100 Closes the ldap connection refered to by the token handle.
101 Returns the empty string as its result.
102 ::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
104 Start TLS negotiation on the connection denoted by handle. This
105 is currently experimental and subject to change.
106 ::ldap::bind handle ?name? ?password?
108 This command authenticates the ldap connection refered to by the
109 token in handle, with a user name and associated password. It
110 blocks until a response from the ldap server arrives. Its result
111 is the empty string. Both name and passwd default to the empty
112 string if they are not specified. By leaving out name and
113 passwd you can make an anonymous bind to the ldap server. You
114 can issue ::ldap::bind again to bind with different credentials.
115 ::ldap::bindSASL handle ?name? ?password?
117 This command uses SASL authentication mechanisms to do a multi‐
118 stage bind. Its otherwise identical to the standard
119 ::ldap::bind. This feature is currently experimental and sub‐
120 ject to change.
121 ::ldap::unbind handle
123 This command asks the ldap server to release the last bind done
124 for the connection refered to by the token in handle. The han‐
125 dle is invalid after the unbind, as the server closes the con‐
126 nection.
127 ::ldap::search handle baseObject filterString attributes ?-scope scope?
129 This command performs a LDAP search below the baseObject tree
130 using a complex LDAP search expression filterString and returns
131 the specified attributes of all matching objects (DNs). If the
132 list of attributes was empty all attributes are returned. The
133 command blocks until it has received all results. The default
134 scope used is subtree, but can be overriden with the -scope
135 option, valid scopes are base, subtree or onelevel.
136 An example of a search expression is
138 set filterString "|(cn=Linus*)(sn=Torvalds*)"
141 The return value of the command is a list of nested dictionar‐
144 ies. The first level keys are object identifiers (DNs), second
145 levels keys are attribute names. In other words, it is in the
146 form
147 {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
150 ::ldap::searchInit handle baseObject filterString attributes options
154 This command initiates a LDAP search below the baseObject tree
155 using a complex LDAP search expression filterString. The search
156 returns the specified attributes of all matching objects (DNs).
157 The initiated search results are returned by subsequent calls to
158 ::ldap::searchNext. A search can be terminated at any time by
159 ::ldap::searchEnd. This informs the server that no further
160 results should be sent. Only one ::ldap::search can be active
161 at a given time, this includes the introspection commands
162 ::ldap::saslmechanisms, ldap::control and ldap::extensions,
163 which invoke a search. Errors from the server are due to wrong
164 arguments or similar things are returned with the first
165 ::ldap::searchNext call and should be checked there. If the
166 list of requested attributes is empty all attributes will be
167 returned. The parameter options specifies the options to be
168 used in the search, and has the following format:
169 {-option1 value1 -option2 value2 ... }
172 Following options are available:
175 -scope base one sub
177 Control the scope of the search to be one of base, one,
178 or sub, to specify a base object, one-level or
179 subtree search. The default is sub.
180 -derefaliases never search find always
182 Control how aliases dereferencing is done. Should be one
183 of never, always, search, or find to specify that
184 aliases are never dereferenced, always dereferenced,
185 dereferenced when searching, or dereferenced only when
186 locating the base object for the search. The default is
187 to never dereference aliases.
188 -sizelimit num
190 Determines the maximum number of entries to return in a
191 search. If specified as 0 no limit is enforced. The
192 server may enforce a configuration dependent sizelimit,
193 which may be lower than the one given by this option. The
194 default is 0, no limit.
195 -timelimit seconds
197 Asks the server to use a timelimit of seconds for the
198 search. Zero means no limit. The default is 0, no limit.
199 -attrsonly boolean
201 If set to 1 only the attribute names but not the values
202 will be present in the search result. The default is to
203 retrieve attribute names and values.
204 ::ldap::searchNext handle
207 This command returns the next entry from a LDAP search initiated
208 by ::ldap::searchInit. The command blocks in a vwait until a new
209 search result is received from the server. The returned entry
210 is a list with two elements: the first is the DN of the entry,
211 the second is the list of attributes and values, under the for‐
212 mat:
213 dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
216 The ::ldap::searchNext command returns an empty list at the end
219 of the search.
220 ::ldap::searchEnd handle
223 This command terminates a LDAP search initiated by
224 ::ldap::searchInit
226 ::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
229 This command modifies the object dn on the ldap server we are
230 connected to via handle. It replaces attributes with new values,
231 deletes attributes, and adds new attributes with new values.
232 All arguments are dictionaries mapping attribute names to val‐
233 ues. The optional arguments default to the empty dictionary,
234 which means that no attributes will be deleted nor added.
235 attrValToReplace dictionary (in)
237 No attributes will be changed if this argument is empty.
238 The dictionary contains the new attributes and their val‐
239 ues. They replace all attributes known to the object.
240 attrToDelete dictionary (in)
242 No attributes will be deleted if this argument is empty.
243 The dictionary values are restrictions on the deletion.
244 An attribute listed here will be deleted if and only if
245 its current value at the server matches the value speci‐
246 fied in the dictionary, or if the value in the dictionary
247 is the empty string.
248 attrValToAdd dictionary (in)
250 No attributes will be added if this argument is empty.
251 The dictionary values are the values for the new
252 attributes.
253 The command blocks until all modifications have completed. Its result
255 is the empty string.
256 ::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attr‐
258 ValToAdd?
259 This command modifies the object dn on the ldap server we are
260 connected to via handle. It replaces attributes with new values,
261 deletes attributes, and adds new attributes with new values.
262 All arguments are lists with the format:
263 attr1 {val11 val12 ...} attr2 {val21...} ...
266 where each value list may be empty for deleting all attributes.
269 The optional arguments default to empty lists of attributes to
270 delete and to add.
271 attrValToReplace list (in)
273 No attributes will be changed if this argument is empty.
274 The dictionary contains the new attributes and their val‐
275 ues. They replace all attributes known to the object.
276 attrValToDelete list (in)
278 No attributes will be deleted if this argument is empty.
279 If no value is specified, the whole set of values for an
280 attribute will be deleted.
281 attrValToAdd list (in)
283 No attributes will be added if this argument is empty.
284 The command blocks until all modifications have completed. Its result
286 is the empty string.
287 ::ldap::add handle dn attrValueTuples
289 This command creates a new object using the specified dn. The
290 attributes of the new object are set to the values in the list
291 attrValueTuples. Multiple valuated attributes may be specified
292 using multiple tuples. The command blocks until the operation
293 has completed. Its result is the empty string.
294 ::ldap::addMulti handle dn attrValueTuples
296 This command is the preferred one to create a new object using
297 the specified dn. The attributes of the new object are set to
298 the values in the dictionary attrValueTuples (which is keyed by
299 the attribute names). Each tuple is a list containing multiple
300 values. The command blocks until the operation has completed.
301 Its result is the empty string.
302 ::ldap::delete handle dn
304 This command removes the object specified by dn, and all its
305 attributes from the server. The command blocks until the opera‐
306 tion has completed. Its result is the empty string.
307 ::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
309 ] This command moves or copies the object specified by dn to a
310 new location in the tree of object. This location is specified
311 by newrdn, a relative designation, or by newrdn and newSuperior,
312 a absolute designation. The optional argument deleteOld
313 defaults to true, i.e. a move operation. If deleteOld is not
314 set, then the operation will create a copy of dn in the new
315 location. The optional argument newSuperior defaults an empty
316 string, meaning that the object must not be relocated in another
317 branch of the tree. If this argument is given, the argument
318 deleteOld must be specified also. The command blocks until the
319 operation has completed. Its result is the empty string.
320 ::ldap::info ip handle
322 This command returns the IP address of the remote LDAP server
323 the handle is connected to.
324 ::ldap::info bound handle
326 This command returns 1 if a handle has successfully completed a
327 ::ldap::bind. If no bound was done or it failed, a 0 is
328 returned.
329 ::ldap::info bounduser handle
331 This command returns the username used in the bind operation if
332 a handle has successfully completed a ::ldap::bind. If no bound
333 was done or it failed, an empty string is returned.
334 ::ldap::info connections
336 This command returns all currently existing ldap connection han‐
337 dles.
338 ::ldap::info tls handle
340 This command returns 1 if the ldap connection handle used
341 TLS/SSL for connection via ldap::secure_connect, 0 otherwise.
342 ::ldap::info saslmechanisms handle
344 Return the supported SASL mechanisms advertised by the server.
345 Only valid in a bound state (anyonmous or other). This is cur‐
346 rently experimental and subject to change.
347 ::ldap::info control handle
349 Return the supported controls advertised by the server as a list
350 of OIDs. Only valid in a bound state. This is currently experi‐
351 mental and subject to change.
352 ::ldap::info extensions extensions
354 Returns the supported LDAP extensions as list of OIDs. Only
355 valid in a bound state. This is currently experimental and sub‐
356 ject to change.
357 ::ldap::info whoami handle
359 Returns authzId for the current connection. This is currently
360 experimental and subject to change.
361
363 A small example, extracted from the test application coming with this
364 code.
365 package require ldap
367 # Connect, bind, add a new object, modify it in various ways
369 set handle [ldap::connect localhost 9009]
371 set dn "cn=Manager, o=University of Michigan, c=US"
373 set pw secret
374 ldap::bind $handle $dn $pw
376 set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
378 ldap::add $handle $dn {
380 objectClass OpenLDAPperson
381 cn {Test User}
382 mail test.user@google.com
383 uid testuid
384 sn User
385 telephoneNumber +31415926535
386 telephoneNumber +27182818285
387 }
388 set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
390 ldap::addMulti $handle $dn {
392 objectClass {OpenLDAPperson}
393 cn {{Anotther User}}
394 mail {test.user@google.com}
395 uid {testuid}
396 sn {User}
397 telephoneNumber {+31415926535 +27182818285}
398 }
399 # Replace all attributes
401 ldap::modify $handle $dn [list drink icetea uid JOLO]
402 # Add some more
404 ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"]
405 # Delete
407 ldap::modify $handle $dn {} [list drink water pager ""]
408 # Move
410 ldap::modifyDN $handle $dn "cn=Tester"
411 # Kill the test object, and shut the connection down.
413 set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
414 ldap::delete $handle $dn
415 ldap::unbind $handle
417 ldap::disconnect $handle
418 And a another example, a simple query, and processing the results.
421 package require ldap
423 set handle [ldap::connect ldap.acme.com 389]
424 ldap::bind $handle
425 set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
426 foreach result $results {
427 foreach {object attributes} $result break
428 # The processing here is similar to what 'parray' does.
430 # I.e. finding the longest attribute name and then
431 # generating properly aligned output listing all attributes
432 # and their values.
433 set width 0
435 set sortedAttribs {}
436 foreach {type values} $attributes {
437 if {[string length $type] > $width} {
438 set width [string length $type]
439 }
440 lappend sortedAttribs [list $type $values]
441 }
442 puts "object='$object'"
444 foreach sortedAttrib $sortedAttribs {
446 foreach {type values} $sortedAttrib break
447 foreach value $values {
448 regsub -all "\[\x01-\x1f\]" $value ? value
449 puts [format " %-${width}s %s" $type $value]
450 }
451 }
452 puts ""
453 }
454 ldap::unbind $handle
455 ldap::disconnect $handle
456
459 asn, ber, directory access, internet, ldap, ldap client, protocol, rfc
460 2251, x.680, x.690
461
463 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
464 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
465 Copyright (c) 2006 Michael Schlenker <mic42@users.sourceforge.net>
466ldap 1.6.6 ldap(n)