1ldapx(n) LDAP extended object interface ldapx(n)
2______________________________________________________________________________
6
8 ldapx - LDAP extended object interface
9
11 package require Tcl 8.4
12 package require ldapx ?1.0?
14 e reset
16 e dn ?newdn?
18 e rdn
20 e superior
22 e print
24 se isempty
26 se get attr
28 se get1 attr
30 se set attr values
32 se set1 attr value
34 se add attr values
36 se add1 attr value
38 se del attr ?values?
40 se del1 attr value
42 se getattr
44 se getall
46 se setall avpairs
48 se backup ?other?
50 se swap
52 se restore ?other?
54 se apply centry
56 ce change ?new?
58 ce diff new ?old?
60 la error ?newmsg?
62 la connect url ?binddn? ?bindpw?
64 la disconnect
66 la traverse base filter attrs entry body
68 la search base filter attrs
70 la read base filter entry ... entry
72 la commit entry ... entry
74 li channel chan
76 li error ?newmsg?
78 li read entry
80 li write entry
82_________________________________________________________________
84
86 The ldapx package provides an extended Tcl interface to LDAP directores
87 and LDIF files. The ldapx package is built upon the ldap package in
88 order to get low level LDAP access.
89 LDAP access is compatible with RFC 2251 (http://www.rfc-edi‐
91 tor.org/rfc/rfc2251.txt). LDIF access is compatible with RFC 2849
92 (http://www.rfc-editor.org/rfc/rfc2849.txt).
93
95 The ldapx package provides objects to interact with LDAP directories
96 and LDIF files with an easy to use programming interface. It imple‐
97 ments three snit::type classes.
98 The first class, entry, is used to store individual entries. Two dif‐
100 ferent formats are available: the first one is the standard format,
101 which represents an entry as read from the directory. The second format
102 is the change format, which stores differences between two standard
103 entries.
104 With these entries, an application which wants to modify an entry in a
106 directory needs to read a (standard) entry from the directory, create a
107 fresh copy into a new (standard) entry, modify the new copy, and then
108 compute the differences between the two entries into a new (change)
109 entry, which may be commited to the directory.
110 Such kinds of modifications are so heavily used that standard entries
112 may contain their own copy of the original data. With such a copy, the
113 application described above reads a (standard) entry from the direc‐
114 tory, backs-up the original data, modifies the entry, and computes the
115 differences between the entry and its backup. These differences are
116 then commited to the directory.
117 Methods are provided to compute differences between two entries, to
119 apply differences to an entry in order to get a new entry, and to get
120 or set attributes in standard entries.
121 The second class is the ldap class. It provides a method to connect and
123 bind to the directory with a uniform access to LDAP and LDAPS through
124 an URL (ldap:// or ldaps://). The traverse control structure executes a
125 body for each entry found in the directory. The commit method applies
126 some changes (represented as entry objects) to the directory. Since
127 some attributes are represented as UTF-8 strings, the option -utf8 con‐
128 trols which attributes must be converted and which attributes must not
129 be converted.
130 The last class is the ldif class. It provides a method to associate a
132 standard Tcl channel to an LDIF object. Then, methods read and write
133 read or write entries from or to this channel. This class can make use
134 of standard or change entries, according to the type of the LDIF file
135 which may contain either standard entries or change entries (but not
136 both at the same time). The option -utf8 works exactly as with the ldap
137 class.
138
140 ENTRY INSTANCE DATA
141 An instance of the entry class keeps the following data:
142 dn This is the DN of the entry, which includes (in LDAP terminol‐
144 ogy) the RDN (relative DN) and the Superior parts.
145 format The format may be uninitialized (entry not yet used), standard
147 or change. Most methods check the format of the entry, which can
148 be reset with the reset method.
149 attrvals
151 In a standard entry, this is where the attributes and associated
152 values are stored. Many methods provide access to these informa‐
153 tions. Attribute names are always converted into lower case.
154 backup In a standard entry, the backup may contain a copy of the dn and
156 all attributes and values. Methods backup and restore manipulate
157 these data, and method diff may use this backup.
158 change In a change entry, these data represent the modifications. Such
160 modifications are handled by specialized methods such as apply
161 or commit. Detailed format should not be used directly by pro‐
162 grams.
163 Internally, modifications are represented as a list of elements,
165 each element has one of the following formats (which match the
166 corresponding LDAP operations):
167 [1] {add {attr1 {val1...valn} attr2 {...} ...}}
169 Addition of a new entry.
171 [2] {mod {modop {attr1 ?val1...valn?} attr2 ...} {modop ...}
173 ...}
174 Modification of one or more attributes and/or values,
176 where <modop> can be modadd, moddel or modrepl (see the
177 LDAP modify operation).
178 [3] {del}
180 Deletion of an old entry.
182 [4] {modrdn newrdn deleteoldrdn ?newsuperior?}
184 Renaming of an entry.
186 ENTRY OPTIONS
188 No option is defined by this class.
189 METHODS FOR ALL KINDS OF ENTRIES
191 e reset
192 This method resets the entry to an uninitialized state.
193 e dn ?newdn?
195 This method returns the current DN of the entry. If the optional
196 newdn is specified, it replaces the current DN of the entry.
197 e rdn This method returns the RDN part of the DN of the entry.
199 e superior
201 This method returns the superior part of the DN of the entry.
202 e print
204 This method returns the entry as a string ready to be printed.
205 METHODS FOR STANDARD ENTRIES ONLY
207 In all methods, attribute names are converted in lower case.
208 se isempty
210 This method returns 1 if the entry is empty (i.e. without any
211 attribute).
212 se get attr
214 This method returns all values of the attribute attr, or the
215 empty list if the attribute is not fond.
216 se get1 attr
218 This method returns the first value of the attribute.
219 se set attr values
221 This method sets the values (list values) of the attribute attr.
222 If the list is empty, this method deletes all
223 se set1 attr value
225 This method sets the values of the attribute attr to be an
226 unique value value. Previous values, if any, are replaced by the
227 new value.
228 se add attr values
230 This method adds all elements the list values to the values of
231 the attribute attr.
232 se add1 attr value
234 This method adds a single value given by the parameter value to
235 the attribute attr.
236 se del attr ?values?
238 If the optional list values is specified, this method deletes
239 all specified values from the attribute attr. If the argument
240 values is not specified, this method deletes all values.
241 se del1 attr value
243 This method deletes a unique value from the attribute attr.
244 se getattr
246 This method returns all attributes names.
247 se getall
249 This method returns all attributes and values from the entry,
250 packed in a list of pairs <attribute, list of values>.
251 se setall avpairs
253 This method sets at once all attributes and values. The format
254 of the avpairs argument is the same as the one returned by
255 method getall.
256 se backup ?other?
258 This method stores in an other standard entry object a copy of
259 the current DN and attributes/values. If the optional other
260 argument is not specified, copy is done in the current entry (in
261 a specific place, see section OVERVIEW).
262 se swap
264 This method swaps the current and backup contexts of the entry.
265 se restore ?other?
267 If the optional argument other is given, which must then be a
268 standard entry, this method restores the current entry into the
269 other entry. If the argument other argument is not specified,
270 this methods restores the current entry from its internal backup
271 (see section OVERVIEW).
272 se apply centry
274 This method applies changes defined in the centry argument,
275 which must be a change entry.
276 METHODS FOR CHANGE ENTRIES ONLY
278 ce change ?new?
279 If the optional argument new is specified, this method modifies
280 the change list (see subsection Entry Instance Data for the
281 exact format). In both cases, current change list is returned.
282 Warning: values returned by this method should only be used by
283 specialized methods such as apply or commit.
284 ce diff new ?old?
286 This method computes the differences between the new and old
287 entries under the form of a change list, and stores this list
288 into the current change entry. If the optional argument old is
289 not specified, difference is computed from the entry and its
290 internal backup (see section OVERVIEW). Return value is the com‐
291 puted change list.
292 ENTRY EXAMPLE
294 package require ldapx
295 #
297 # Create an entry and fill it as a standard entry with
298 # attributes and values
299 #
300 ::ldapx::entry create e
301 e dn "uid=joe,ou=people,o=mycomp"
302 e set1 "uid" "joe"
303 e set "objectClass" {person anotherObjectClass}
304 e set1 "givenName" "Joe"
305 e set1 "sn" "User"
306 e set "telephoneNumber" {+31415926535 +2182818}
307 e set1 "anotherAttr" "This is a beautiful day, isn't it?"
308 puts stdout "e\n[e print]"
310 #
312 # Create a second entry as a backup of the first, and
313 # make some changes on it.
314 # Entry is named automatically by snit.
315 #
316 set b [::ldapx::entry create %AUTO%]
318 e backup $b
319 puts stdout "$b\n[$b print]"
321 $b del "anotherAttr"
323 $b del1 "objectClass" "anotherObjectClass"
324 #
326 # Create a change entry, a compute differences between first
327 # and second entry.
328 #
329 ::ldapx::entry create c
331 c diff e $b
332 puts stdout "$c\n[$c print]"
334 #
336 # Apply changes to first entry. It should be the same as the
337 # second entry, now.
338 #
339 e apply c
341 ::ldapx::entry create nc
343 nc diff e $b
344 puts stdout "nc\n[nc print]"
346 #
348 # Clean-up
349 #
350 e destroy
352 $b destroy
353 c destroy
354 nc destroy
355
358 LDAP INSTANCE DATA
359 An instance of the ldap class keeps the following data:
360 channel
362 This is the channel used by the ldap package for communication
363 with the LDAP server.
364 lastError
366 This variable contains the error message which appeared in the
367 last method of the ldap class (this string is modified in nearly
368 all methods). The error method may be used to fetch this mes‐
369 sage.
370 LDAP OPTIONS
372 A first set of options of the ldap class is used during search opera‐
373 tions (methods traverse, search and read, see below).
374 -scope base|one|sub
376 Specify the scope of the LDAP search to be one of base, one or
377 sub to specify a base object, one-level or subtree search.
378 The default is sub.
380 -derefaliases never|seach|find|always
382 Specify how aliases dereferencing is handled: never is used to
383 specify that aliases are never derefenced, always that aliases
384 are always derefenced, search that aliases are dereferenced when
385 searching, or find that aliases are dereferenced only when
386 locating the base object for the search.
387 The default is never.
389 -sizelimit integer
391 Specify the maximum number of entries to be retreived during a
392 search. A value of 0 means no limit.
393 Default is 0.
395 -timelimit integer
397 Specify the time limit for a search to complete. A value of 0
398 means no limit.
399 Default is 0.
401 -attrsonly 0|1
403 Specify if only attribute names are to be retrieved (value 1).
404 Normally (value 0), attribute values are also retrieved.
405 Default is 0.
407 The last option is used when getting entries or committing changes in
409 the directory:
410 -utf8 pattern-yes pattern-no
412 Specify which attribute values are encoded in UTF-8. This infor‐
413 mation is specific to the LDAP schema in use by the application,
414 since some attributes such as jpegPhoto, for example, are not
415 encoded in UTF-8. This option takes the form of a list with two
416 regular expressions suitable for the regexp command (anchored by
417 ^ and $). The first specifies which attribute names are to be
418 UTF-8 encoded, and the second selects, among those, the
419 attribute names which will not be UTF-8 encoded. It is thus
420 possible to say: convert all attributes, except jpegPhoto.
421 Default is {{.*} {}}, meaning: all attributes are converted,
423 without exception.
424 LDAP METHODS
426 la error ?newmsg?
427 This method returns the error message that occurred in the last
428 call to a ldap class method. If the optional argument newmsg is
429 supplied, it becomes the last error message.
430 la connect url ?binddn? ?bindpw?
432 This method connects to the LDAP server using given URL (which
433 can be of the form ldap://host:port or ldaps://host:port). If an
434 optional binddn argument is given together with the bindpw argu‐
435 ment, the connect binds to the LDAP server using the specified
436 DN and password.
437 la disconnect
439 This method disconnects (and unbinds, if necessary) from the
440 LDAP server.
441 la traverse base filter attrs entry body
443 This method is a new control structure. It searches the LDAP
444 directory from the specified base DN (given by the base argu‐
445 ment) and selects entries based on the argument filter. For each
446 entry found, this method fetches attributes specified by the
447 attrs argument (or all attributes if it is an empty list),
448 stores them in the entry instance of class entry and executes
449 the script defined by the argument body. Options are used to
450 refine the search.
451 Caution: when this method is used, the script body cannot per‐
453 form another LDAP search (methods traverse, search or read).
454 la search base filter attrs
456 This method searches the directory using the same way as method
457 traverse. All found entries are stored in newly created
458 instances of class entry, which are returned in a list. The
459 newly created instances should be destroyed when they are no
460 longer used.
461 la read base filter entry ... entry
463 This method reads one or more entries, using the same search
464 criteria as methods traverse and search. All attributes are
465 stored in the entries. This method provides a quick way to read
466 some entries. It returns the number of entries found in the
467 directory (which may be more than the number of read entries).
468 If called without any entry argument, this method just returns
469 the number of entries found, without returning any data.
470 la commit entry ... entry
472 This method commits the changes stored in the entry arguments.
473 Each entry may be either a change entry, or a standard entry
474 with a backup.
475 Note: in the future, this method should use the LDAP transaction
477 extension provided by OpenLDAP 2.3 and later.
478 LDAP EXAMPLE
480 package require ldapx
481 #
483 # Connects to the LDAP directory
484 #
485 ::ldapx::ldap create l
487 set url "ldap://server.mycomp.com"
488 if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
489 puts stderr "error: [l error]"
490 exit 1
491 }
492 #
494 # Search all entries matching some criterion
495 #
496 l configure -scope one
498 ::ldapx::ldap create e
499 set n 0
500 l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
501 puts "dn: [e dn]"
502 puts " sn: [e get1 sn]"
503 puts " givenName: [e get1 givenName]"
504 incr n
505 }
506 puts "$n entries found"
507 e destroy
508 #
510 # Add a telephone number to some entries
511 # Note this modification cannot be done in the "traverse" operation.
512 #
513 set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
515 ::ldapx::ldap create c
516 foreach e $lent {
517 $e backup
518 $e add1 "telephoneNumber" "+31415926535"
519 c diff $e
520 if {! [l commit c]} then {
521 puts stderr "error: [l error]"
522 exit 1
523 }
524 $e destroy
525 }
526 l disconnect
528 l destroy
529
532 LDIF INSTANCE DATA
533 An instance of the ldif class keeps the following data:
534 channel
536 This is the Tcl channel used to retrieve or store LDIF file con‐
537 tents. The association between an instance and a channel is made
538 by the method channel. There is no need to disrupt this associa‐
539 tion when the LDIF file operation has ended.
540 format LDIF files may contain standard entries or change entries, but
542 not both. This variable contains the detected format of the file
543 (when reading) or the format of entries written to the file
544 (when writing).
545 lastError
547 This variable contains the error message which appeared in the
548 last method of the ldif class (this string is modified in nearly
549 all methods). The error method may be used to fetch this mes‐
550 sage.
551 version
553 This is the version of the LDIF file. Only version 1 is sup‐
554 ported: the method read can only read from version 1 files, and
555 method write only creates version 1 files.
556 LDIF OPTIONS
558 This class defines two options:
559 -ignore list-of-attributes
561 This option is used to ignore certain attribute names on read‐
562 ing. For example, to read OpenLDAP replica files (replog), one
563 must ignore replica and time attributes since they do not con‐
564 form to the RFC 2849 standard for LDIF files.
565 Default is empty list: no attribute is ignored.
567 -utf8 pattern-yes pattern-no
569 Specify which attribute values are encoded in UTF-8. This infor‐
570 mation is specific to the LDAP schema in use by the application,
571 since some attributes such as jpegPhoto, for example, are not
572 encoded in UTF-8. This option takes the form of a list with two
573 regular expressions suitable for the regexp command (anchored by
574 ^ and $). The first specifies which attribute names are to be
575 UTF-8 encoded, and the second selects, among those, the
576 attribute names which will not be UTF-8 encoded. It is thus
577 possible to say: convert all attributes, except jpegPhoto.
578 Default is {{.*} {}}, meaning: all attributes are converted,
580 without exception.
581 LDIF METHODS
583 li channel chan
584 This method associates the Tcl channel named chan with the LDIF
585 instance. It resets the type of LDIF object to uninitialized.
586 li error ?newmsg?
588 This method returns the error message that occurred in the last
589 call to a ldif class method. If the optional argument newmsg is
590 supplied, it becomes the last error message.
591 li read entry
593 This method reads the next entry from the LDIF file and stores
594 it in the entry object of class entry. The entry may be a stan‐
595 dard or change entry.
596 li write entry
598 This method writes the entry given in the argument entry to the
599 LDIF file.
600 LDIF EXAMPLE
602 package require ldapx
603 # This examples reads a LDIF file containing entries,
605 # compare them to a LDAP directory, and writes on standard
606 # output an LDIF file containing changes to apply to the
607 # LDAP directory to match exactly the LDIF file.
608 ::ldapx::ldif create liin
610 liin channel stdin
611 ::ldapx::ldif create liout
613 liout channel stdout
614 ::ldapx::ldap create la
616 if {! [la connect "ldap://server.mycomp.com"]} then {
617 puts stderr "error: [la error]"
618 exit 1
619 }
620 la configure -scope one
621 # Reads LDIF file
623 ::ldapx::entry create e1
625 ::ldapx::entry create e2
626 ::ldapx::entry create c
627 while {[liin read e1] != 0} {
629 set base [e1 superior]
630 set id [e1 rdn]
631 if {[la read $base "($id)" e2] == 0} then {
632 e2 reset
633 }
634 c diff e1 e2
636 if {[llength [c change]] != 0} then {
637 liout write c
638 }
639 }
640 la disconnect
642 la destroy
643 e1 destroy
644 e2 destroy
645 c destroy
646 liout destroy
647 liin destroy
648
652 This document, and the package it describes, will undoubtedly contain
653 bugs and other problems. Please report such in the category ldap of
654 the Tcllib SF Trackers [http://source‐
655 forge.net/tracker/?group_id=12883]. Please also report any ideas for
656 enhancements you may have for either package and/or documentation.
657
659 directory access, internet, ldap, ldap client, ldif, protocol, rfc
660 2251, rfc 2849
661
663 Copyright (c) 2006 Pierre David <pdav@users.sourceforge.net>
664ldap 0.2.5 ldapx(n)