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 ?0.2.2?
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).
137
139 Entry Instance Data
140 An instance of the entry class keeps the following data:
141 dn This is the DN of the entry, which includes (in LDAP terminol‐
143 ogy) the RDN (relative DN) and the Superior parts.
144 format The format may be uninitialized (entry not yet used), standard
146 or change. Most methods check the format of the entry, which can
147 be reset with the reset method.
148 attrvals
150 In a standard entry, this is where the attributes and associated
151 values are stored. Many methods provide access to these informa‐
152 tions. Attribute names are always converted into lower case.
153 backup In a standard entry, the backup may contain a copy of the dn and
155 all attributes and values. Methods backup and restore manipulate
156 these data, and method diff may use this backup.
157 change In a change entry, these data represent the modifications. They
159 are represented as a list with one of the following formats
160 (which match the corresponding LDAP operations):
161 [1] {} (empty list)
163 No modification at all.
165 [2] {add {attr1 {val1...valn} attr2 {...} ...}}
167 This change represents the addition of a new entry.
169 [3] {mod {modop {attr1 ?val1...valn?} attr2 ...} {modop ...}
171 ...}
172 This change represents the modification of one or more
174 attributes and/or values, where <modop> can be modadd,
175 moddel or modrepl (see the LDAP modify operation).
176 [4] {del}
178 This change represents the deletion of an old entry.
180 [5] {modrdn newrdn deleteoldrdn ?newsuperior?}
182 This change represents the copy or the renaming of an
184 entry.
185 Entry Options
187 No option is defined by this class.
188 Methods for all kinds of entries
190 e reset
191 This method resets the entry to an uninitialized state.
192 e dn ?newdn?
194 This method returns the current DN of the entry. If the optional
195 newdn is specified, it replaces the current DN of the entry.
196 e rdn This method returns the RDN part of the DN of the entry.
198 e superior
200 This method returns the superior part of the DN of the entry.
201 e print
203 This method returns the entry as a string ready to be printed.
204 Methods for standard entries only
206 In all methods, attribute names are converted in lower case.
207 se isempty
209 This method returns 1 if the entry is empty (i.e. without any
210 attribute).
211 se get attr
213 This method returns all values of the attribute attr, or the
214 empty list if the attribute is not fond.
215 se get1 attr
217 This method returns the first value of the attribute.
218 se set attr values
220 This method sets the values (list values) of the attribute attr.
221 If the list is empty, this method deletes all
222 se set1 attr value
224 This method sets the values of the attribute attr to be an
225 unique value value. Previous values, if any, are replaced by the
226 new value.
227 se add attr values
229 This method adds all elements the list values to the values of
230 the attribute attr.
231 se add1 attr value
233 This method adds a single value given by the parameter value to
234 the attribute attr.
235 se del attr ?values?
237 If the optional list values is specified, this method deletes
238 all specified values from the attribute attr. If the argument
239 values is not specified, this method deletes all values.
240 se del1 attr value
242 This method deletes a unique value from the attribute attr.
243 se getattr
245 This method returns all attributes names.
246 se getall
248 This method returns all attributes and values from the entry,
249 packed in a list of pairs <attribute, list of values>.
250 se setall avpairs
252 This method sets at once all attributes and values. The format
253 of the avpairs argument is the same as the one returned by
254 method getall.
255 se backup ?other?
257 This method stores in an other standard entry object a copy of
258 the current DN and attributes/values. If the optional other
259 argument is not specified, copy is done in the current entry (in
260 a specific place, see section OVERVIEW).
261 se swap
263 This method swaps the current and backup contexts of the entry.
264 se restore ?other?
266 If the optional argument other is given, which must then be a
267 standard entry, this method restores the current entry into the
268 other entry. If the argument other argument is not specified,
269 this methods restores the current entry from its internal backup
270 (see section OVERVIEW).
271 se apply centry
273 This method applies changes defined in the centry argument,
274 which must be a change entry.
275 Methods for change entries only
277 ce change ?new?
278 If the optional argument new is specified, this method modifies
279 the change list (see subsection Data for the exact format). In
280 both cases, current change list is returned.
281 ce diff new ?old?
283 This method computes the differences between the new and old
284 entries under the form of a change list, and stores this list
285 into the current change entry. If the optional argument old is
286 not specified, difference is computed from the entry and its
287 internal backup (see section OVERVIEW).
288 Entry Example
290 package require ldapx
291 #
293 # Create an entry and fill it as a standard entry with
294 # attributes and values
295 #
296 ::ldapx::entry create e
297 e dn "uid=joe,ou=people,o=mycomp"
298 e set1 "uid" "joe"
299 e set "objectClass" {person anotherObjectClass}
300 e set1 "givenName" "Joe"
301 e set1 "sn" "User"
302 e set "telephoneNumber" {+31415926535 +2182818}
303 e set1 "anotherAttr" "This is a beautiful day, isn't it?"
304 puts stdout "e\n[e print]"
306 #
308 # Create a second entry as a backup of the first, and
309 # make some changes on it.
310 # Entry is named automatically by snit.
311 #
312 set b [::ldapx::entry create %AUTO%]
314 e backup $b
315 puts stdout "$b\n[$b print]"
317 $b del "anotherAttr"
319 $b del1 "objectClass" "anotherObjectClass"
320 #
322 # Create a change entry, a compute differences between first
323 # and second entry.
324 #
325 ::ldapx::entry create c
327 c diff e $b
328 puts stdout "$c\n[$c print]"
330 #
332 # Apply changes to first entry. It should be the same as the
333 # second entry, now.
334 #
335 e apply c
337 ::ldapx::entry create nc
339 nc diff e $b
340 puts stdout "nc\n[nc print]"
342 #
344 # Clean-up
345 #
346 e destroy
348 $b destroy
349 c destroy
350 nc destroy
351
354 Ldap Instance Data
355 An instance of the ldap class keeps the following data:
356 channel
358 This is the channel used by the ldap package for communication
359 with the LDAP server.
360 lastError
362 This variable contains the error message which appeared in the
363 last method of the ldap class (this string is modified in nearly
364 all methods). The error method may be used to fetch this mes‐
365 sage.
366 Ldap Options
368 A first set of options of the ldap class is used during search opera‐
369 tions (methods traverse, search and read, see below).
370 -scope base|one|sub
372 Specify the scope of the LDAP search to be one of base, one or
373 sub to specify a base object, one-level or subtree search.
374 The default is sub.
376 -derefaliases never|seach|find|always
378 Specify how aliases dereferencing is handled: never is used to
379 specify that aliases are never derefenced, always that aliases
380 are always derefenced, search that aliases are dereferenced when
381 searching, or find that aliases are dereferenced only when
382 locating the base object for the search.
383 The default is never.
385 -sizelimit integer
387 Specify the maximum number of entries to be retreived during a
388 search. A value of 0 means no limit.
389 Default is 0.
391 -timelimit integer
393 Specify the time limit for a search to complete. A value of 0
394 means no limit.
395 Default is 0.
397 -attrsonly 0|1
399 Specify if only attribute names are to be retrieved (value 1).
400 Normally (value 0), attribute values are also retrieved.
401 Default is 0.
403 The last option is used when getting entries or committing changes in
405 the directory:
406 -utf8 pattern-yes pattern-no
408 Specify which attribute values are encoded in UTF-8. This infor‐
409 mation is specific to the LDAP schema in use by the application,
410 since some attributes such as jpegPhoto, for example, are not
411 encoded in UTF-8. This option takes the form of a list with two
412 regular expressions suitable for the regexp command (anchored by
413 ^ and $). The first specifies which attribute names are to be
414 UTF-8 encoded, and the second selects, among those, the
415 attribute names which will not be UTF-8 encoded. It is thus
416 possible to say: convert all attributes, except jpegPhoto.
417 Default is {{.*} {}}, meaning: all attributes are converted,
419 without exception.
420 Ldap Methods
422 la error ?newmsg?
423 This method returns the error message that occurred in the last
424 call to a ldap class method. If the optional argument newmsg is
425 supplied, it becomes the last error message.
426 la connect url ?binddn? ?bindpw?
428 This method connects to the LDAP server using given URL (which
429 can be of the form ldap://host:port or ldaps://host:port). If an
430 optional binddn argument is given together with the bindpw argu‐
431 ment, the connect binds to the LDAP server using the specified
432 DN and password.
433 la disconnect
435 This method disconnects (and unbinds, if necessary) from the
436 LDAP server.
437 la traverse base filter attrs entry body
439 This method is a new control structure. It searches the LDAP
440 directory from the specified base DN (given by the base argu‐
441 ment) and selects entries based on the argument filter. For each
442 entry found, this method fetches attributes specified by the
443 attrs argument (or all attributes if it is an empty list),
444 stores them in the entry instance of class entry and executes
445 the script defined by the argument body. Options are used to
446 refine the search.
447 Caution: when this method is used, the script body cannot per‐
449 form another LDAP search (methods traverse, search or read).
450 la search base filter attrs
452 This method searches the directory using the same way as method
453 traverse. All found entries are stored in newly created
454 instances of class entry, which are returned in a list. The
455 newly created instances should be destroyed when they are no
456 longer used.
457 la read base filter entry ... entry
459 This method reads one or more entries, using the same search
460 criteria as methods traverse and search. All attributes are
461 stored in the entries. This method provides a quick way to read
462 some entries. It returns the number of entries found in the
463 directory (which may be more than the number of read entries).
464 If called without any entry argument, this method just returns
465 the number of entries found, without returning any data.
466 la commit entry ... entry
468 This method commits the changes stored in the entry arguments.
469 Each entry may be either a change entry, or a standard entry
470 with a backup.
471 Note: in the future, this method should use the LDAP transaction
473 extension provided by OpenLDAP 2.3 and later.
474 Ldap Example
476 package require ldapx
477 #
479 # Connects to the LDAP directory
480 #
481 ::ldapx::ldap create l
483 set url "ldap://server.mycomp.com"
484 if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
485 puts stderr "error: [l error]"
486 exit 1
487 }
488 #
490 # Search all entries matching some criterion
491 #
492 l configure -scope one
494 ::ldapx::ldap create e
495 set n 0
496 l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
497 puts "dn: [e dn]"
498 puts " sn: [e get1 sn]"
499 puts " givenName: [e get1 givenName]"
500 incr n
501 }
502 puts "$n entries found"
503 e destroy
504 #
506 # Add a telephone number to some entries
507 # Note this modification cannot be done in the "traverse" operation.
508 #
509 set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
511 ::ldapx::ldap create c
512 foreach e $lent {
513 $e backup
514 $e add1 "telephoneNumber" "+31415926535"
515 c diff $e
516 if {! [l commit c]} then {
517 puts stderr "error: [l error]"
518 exit 1
519 }
520 $e destroy
521 }
522 l disconnect
524 l destroy
525
528 Ldif Instance Data
529 An instance of the ldif class keeps the following data:
530 channel
532 This is the Tcl channel used to retrieve or store LDIF file con‐
533 tents. The association between an instance and a channel is made
534 by the method channel. There is no need to disrupt this associa‐
535 tion when the LDIF file operation has ended.
536 format LDIF files may contain standard entries or change entries, but
538 not both. This variable contains the detected format of the file
539 (when reading) or the format of entries written to the file
540 (when writing).
541 lastError
543 This variable contains the error message which appeared in the
544 last method of the ldif class (this string is modified in nearly
545 all methods). The error method may be used to fetch this mes‐
546 sage.
547 version
549 This is the version of the LDIF file. Only version 1 is sup‐
550 ported: the method read can only read from version 1 files, and
551 method write only creates version 1 files.
552 Ldif Options
554 This class defines one option:
555 -ignore list-of-attributes
557 This option is used to ignore certain attribute names on read‐
558 ing. For example, to read OpenLDAP replica files (replog), one
559 must ignore replica and time attributes since they do not con‐
560 form to the RFC 2849 standard for LDIF files.
561 Default is empty list: no attribute is ignored.
563 Ldif Methods
565 li channel chan
566 This method associates the Tcl channel named chan with the LDIF
567 instance. It resets the type of LDIF object to uninitialized.
568 li error ?newmsg?
570 This method returns the error message that occurred in the last
571 call to a ldif class method. If the optional argument newmsg is
572 supplied, it becomes the last error message.
573 li read entry
575 This method reads the next entry from the LDIF file and stores
576 it in the entry object of class entry. The entry may be a stan‐
577 dard or change entry.
578 li write entry
580 This method writes the entry given in the argument entry to the
581 LDIF file.
582 Ldif Example
584 package require ldapx
585 # This examples reads a LDIF file containing entries,
587 # compare them to a LDAP directory, and writes on standard
588 # output an LDIF file containing changes to apply to the
589 # LDAP directory to match exactly the LDIF file.
590 ::ldapx::ldif create liin
592 liin channel stdin
593 ::ldapx::ldif create liout
595 liout channel stdout
596 ::ldapx::ldap create la
598 if {! [la connect "ldap://server.mycomp.com"]} then {
599 puts stderr "error: [la error]"
600 exit 1
601 }
602 la configure -scope one
603 # Reads LDIF file
605 ::ldapx::entry create e1
607 ::ldapx::entry create e2
608 ::ldapx::entry create c
609 while {[liin read e1] != 0} {
611 set base [e1 superior]
612 set id [e1 rdn]
613 if {[la read $base "($id)" e2] == 0} then {
614 e2 reset
615 }
616 c diff e1 e2
618 if {[llength [c change]] != 0} then {
619 liout write c
620 }
621 }
622 la disconnect
624 la destroy
625 e1 destroy
626 e2 destroy
627 c destroy
628 liout destroy
629 liin destroy
630
634 directory access, internet, ldap, ldap client, ldif, protocol, rfc
635 2251, rfc 2849
636
638 Copyright (c) 2006 Pierre David <pdav@users.sourceforge.net>
639ldap 0.2.2 ldapx(n)