1ldapx(n) LDAP extended object interface ldapx(n)
2______________________________________________________________________________
6
8 ldapx - LDAP extended object interface
9
11 package require Tcl 8.5
12 package require ldapx ?1.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? ?starttls?
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 or‐
88 der 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 en‐
103 tries.
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) en‐
109 try, 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 ap‐
119 ply differences to an entry in order to get a new entry, and to get or
120 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 ar‐
260 gument is not specified, copy is done in the current entry (in a
261 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 ex‐
281 act 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 en‐
287 tries under the form of a change list, and stores this list into
288 the current change entry. If the optional argument old is not
289 specified, difference is computed from the entry and its inter‐
290 nal backup (see section OVERVIEW). Return value is the computed
291 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 Options are configured on ldap instances using the configure method.
373 The first option is used for TLS parameters:
375 -tlsoptions list
377 Specify the set of TLS options to use when connecting to the
378 LDAP server (see the connect method). For the list of valid op‐
379 tions, see the LDAP package documentation.
380 The default is -request 1 -require 1 -ssl2 no -ssl3 no -tls1 yes
382 -tls1.1 yes -tls1.2 yes.
383 Example:
385 $l configure -tlsoptions {-request yes -require yes}
388 A set of options of the ldap class is used during search operations
390 (methods traverse, search and read, see below).
391 -scope base|one|sub
393 Specify the scope of the LDAP search to be one of base, one or
394 sub to specify a base object, one-level or subtree search.
395 The default is sub.
397 -derefaliases never|seach|find|always
399 Specify how aliases dereferencing is handled: never is used to
400 specify that aliases are never derefenced, always that aliases
401 are always derefenced, search that aliases are dereferenced when
402 searching, or find that aliases are dereferenced only when lo‐
403 cating the base object for the search.
404 The default is never.
406 -sizelimit integer
408 Specify the maximum number of entries to be retreived during a
409 search. A value of 0 means no limit.
410 Default is 0.
412 -timelimit integer
414 Specify the time limit for a search to complete. A value of 0
415 means no limit.
416 Default is 0.
418 -attrsonly 0|1
420 Specify if only attribute names are to be retrieved (value 1).
421 Normally (value 0), attribute values are also retrieved.
422 Default is 0.
424 The last option is used when getting entries or committing changes in
426 the directory:
427 -utf8 pattern-yes pattern-no
429 Specify which attribute values are encoded in UTF-8. This infor‐
430 mation is specific to the LDAP schema in use by the application,
431 since some attributes such as jpegPhoto, for example, are not
432 encoded in UTF-8. This option takes the form of a list with two
433 regular expressions suitable for the regexp command (anchored by
434 ^ and $). The first specifies which attribute names are to be
435 UTF-8 encoded, and the second selects, among those, the attri‐
436 bute names which will not be UTF-8 encoded. It is thus possible
437 to say: convert all attributes, except jpegPhoto.
438 Default is {{.*} {}}, meaning: all attributes are converted,
440 without exception.
441 LDAP METHODS
443 la error ?newmsg?
444 This method returns the error message that occurred in the last
445 call to a ldap class method. If the optional argument newmsg is
446 supplied, it becomes the last error message.
447 la connect url ?binddn? ?bindpw? ?starttls?
449 This method connects to the LDAP server using given URL (which
450 can be of the form ldap://host:port or ldaps://host:port). If an
451 optional binddn argument is given together with the bindpw argu‐
452 ment, the connect binds to the LDAP server using the specified
453 DN and password.
454 If the starttls argument is given a true value (1, yes, etc.)
456 and the URL uses the ldap:// scheme, a TLS negotiation is initi‐
457 ated with the newly created connection, before LDAP binding.
458 Default value: no.
459 This method returns 1 if connection was successful, or 0 if an
461 error occurred (use the error method to get the message).
462 la disconnect
464 This method disconnects (and unbinds, if necessary) from the
465 LDAP server.
466 la traverse base filter attrs entry body
468 This method is a new control structure. It searches the LDAP di‐
469 rectory from the specified base DN (given by the base argument)
470 and selects entries based on the argument filter. For each entry
471 found, this method fetches attributes specified by the attrs ar‐
472 gument (or all attributes if it is an empty list), stores them
473 in the entry instance of class entry and executes the script de‐
474 fined by the argument body. Options are used to refine the
475 search.
476 Caution: when this method is used, the script body cannot per‐
478 form another LDAP search (methods traverse, search or read).
479 la search base filter attrs
481 This method searches the directory using the same way as method
482 traverse. All found entries are stored in newly created in‐
483 stances of class entry, which are returned in a list. The newly
484 created instances should be destroyed when they are no longer
485 used.
486 la read base filter entry ... entry
488 This method reads one or more entries, using the same search
489 criteria as methods traverse and search. All attributes are
490 stored in the entries. This method provides a quick way to read
491 some entries. It returns the number of entries found in the di‐
492 rectory (which may be more than the number of read entries). If
493 called without any entry argument, this method just returns the
494 number of entries found, without returning any data.
495 la commit entry ... entry
497 This method commits the changes stored in the entry arguments.
498 Each entry may be either a change entry, or a standard entry
499 with a backup.
500 Note: in the future, this method should use the LDAP transaction
502 extension provided by OpenLDAP 2.3 and later.
503 LDAP EXAMPLE
505 package require ldapx
506 #
508 # Connects to the LDAP directory using StartTLS
509 #
510 ::ldapx::ldap create l
512 l configure -tlsoptions {-cadir /etc/ssl/certs -request yes -require yes}
513 set url "ldap://server.mycomp.com"
514 if {! [l connect $url "cn=admin,o=mycomp" "mypasswd" yes]} then {
515 puts stderr "error: [l error]"
516 exit 1
517 }
518 #
520 # Search all entries matching some criterion
521 #
522 l configure -scope one
524 ::ldapx::entry create e
525 set n 0
526 l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
527 puts "dn: [e dn]"
528 puts " sn: [e get1 sn]"
529 puts " givenName: [e get1 givenName]"
530 incr n
531 }
532 puts "$n entries found"
533 e destroy
534 #
536 # Add a telephone number to some entries
537 # Note this modification cannot be done in the "traverse" operation.
538 #
539 set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
541 ::ldapx::entry create c
542 foreach e $lent {
543 $e backup
544 $e add1 "telephoneNumber" "+31415926535"
545 c diff $e
546 if {! [l commit c]} then {
547 puts stderr "error: [l error]"
548 exit 1
549 }
550 $e destroy
551 }
552 c destroy
553 l disconnect
555 l destroy
556
559 LDIF INSTANCE DATA
560 An instance of the ldif class keeps the following data:
561 channel
563 This is the Tcl channel used to retrieve or store LDIF file con‐
564 tents. The association between an instance and a channel is made
565 by the method channel. There is no need to disrupt this associa‐
566 tion when the LDIF file operation has ended.
567 format LDIF files may contain standard entries or change entries, but
569 not both. This variable contains the detected format of the file
570 (when reading) or the format of entries written to the file
571 (when writing).
572 lastError
574 This variable contains the error message which appeared in the
575 last method of the ldif class (this string is modified in nearly
576 all methods). The error method may be used to fetch this mes‐
577 sage.
578 version
580 This is the version of the LDIF file. Only version 1 is sup‐
581 ported: the method read can only read from version 1 files, and
582 method write only creates version 1 files.
583 LDIF OPTIONS
585 This class defines two options:
586 -ignore list-of-attributes
588 This option is used to ignore certain attribute names on read‐
589 ing. For example, to read OpenLDAP replica files (replog), one
590 must ignore replica and time attributes since they do not con‐
591 form to the RFC 2849 standard for LDIF files.
592 Default is empty list: no attribute is ignored.
594 -utf8 pattern-yes pattern-no
596 Specify which attribute values are encoded in UTF-8. This infor‐
597 mation is specific to the LDAP schema in use by the application,
598 since some attributes such as jpegPhoto, for example, are not
599 encoded in UTF-8. This option takes the form of a list with two
600 regular expressions suitable for the regexp command (anchored by
601 ^ and $). The first specifies which attribute names are to be
602 UTF-8 encoded, and the second selects, among those, the attri‐
603 bute names which will not be UTF-8 encoded. It is thus possible
604 to say: convert all attributes, except jpegPhoto.
605 Default is {{.*} {}}, meaning: all attributes are converted,
607 without exception.
608 LDIF METHODS
610 li channel chan
611 This method associates the Tcl channel named chan with the LDIF
612 instance. It resets the type of LDIF object to uninitialized.
613 li error ?newmsg?
615 This method returns the error message that occurred in the last
616 call to a ldif class method. If the optional argument newmsg is
617 supplied, it becomes the last error message.
618 li read entry
620 This method reads the next entry from the LDIF file and stores
621 it in the entry object of class entry. The entry may be a stan‐
622 dard or change entry.
623 li write entry
625 This method writes the entry given in the argument entry to the
626 LDIF file.
627 LDIF EXAMPLE
629 package require ldapx
630 # This examples reads a LDIF file containing entries,
632 # compare them to a LDAP directory, and writes on standard
633 # output an LDIF file containing changes to apply to the
634 # LDAP directory to match exactly the LDIF file.
635 ::ldapx::ldif create liin
637 liin channel stdin
638 ::ldapx::ldif create liout
640 liout channel stdout
641 ::ldapx::ldap create la
643 if {! [la connect "ldap://server.mycomp.com"]} then {
644 puts stderr "error: [la error]"
645 exit 1
646 }
647 la configure -scope one
648 # Reads LDIF file
650 ::ldapx::entry create e1
652 ::ldapx::entry create e2
653 ::ldapx::entry create c
654 while {[liin read e1] != 0} {
656 set base [e1 superior]
657 set id [e1 rdn]
658 if {[la read $base "($id)" e2] == 0} then {
659 e2 reset
660 }
661 c diff e1 e2
663 if {[llength [c change]] != 0} then {
664 liout write c
665 }
666 }
667 la disconnect
669 la destroy
670 e1 destroy
671 e2 destroy
672 c destroy
673 liout destroy
674 liin destroy
675
679 This document, and the package it describes, will undoubtedly contain
680 bugs and other problems. Please report such in the category ldap of
681 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
682 also report any ideas for enhancements you may have for either package
683 and/or documentation.
684 When proposing code changes, please provide unified diffs, i.e the out‐
686 put of diff -u.
687 Note further that attachments are strongly preferred over inlined
689 patches. Attachments can be made by going to the Edit form of the
690 ticket immediately after its creation, and then using the left-most
691 button in the secondary navigation bar.
692
694 directory access, internet, ldap, ldap client, ldif, protocol, rfc
695 2251, rfc 2849
696
698 Networking
699
701 Copyright (c) 2006-2018 Pierre David <pdav@users.sourceforge.net>
702tcllib 1.2 ldapx(n)