← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/likewise-open/oneiric

« back to all changes in this revision

Viewing changes to openldap/contrib/ldaptcl/ldap.n

  • Committer: Bazaar Package Importer
  • Author(s): Scott Salley
  • Date: 2010-11-22 12:06:00 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20101122120600-8lba1fpceot71wlb
Tags: 6.0.0.53010-1
Likewise Open 6.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
openldap/contrib/ldaptcl/ldap.n
 
1
'\"
 
2
'\" Copyright (c) 1998 NeoSoft, Inc.
 
3
'\"
 
4
'\" See the file "license.terms" for information on usage and redistribution
 
5
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 
6
'\"
 
7
.so man.macros
 
8
.TH ldap n "" Ldap "Ldap Tcl Extension"
 
9
.BS
 
10
'\" Note:  do not modify the .SH NAME line immediately below!
 
11
.SH NAME
 
12
ldap \- connect to and query an LDAP server
 
13
.SH SYNOPSIS
 
14
\fBldap \fBopen \fR \fIcommand\fR \fIhostlist\fR
 
15
.br
 
16
\fBldap \fBinit \fR \fIcommand\fR \fIhostlist\fR ?protocol_version [2|3]?
 
17
.br
 
18
\fBldap \fBexplode ?-nonames|-list?\fR \fIdn\fR
 
19
.br
 
20
\fIcommand \fBsubcommand \fIoptions ...\fR
 
21
.BE
 
22
 
 
23
.SH OVERVIEW
 
24
.PP
 
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 or exhausts the list.
 
30
.PP
 
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.
 
34
.PP
 
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.
 
37
.SH DESCRIPTION
 
38
 
 
39
The Lightweight Directory Access Protocol provides TCP/IP access to
 
40
X.500 directory services and/or to a stand-alone LDAP server.
 
41
 
 
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.
 
48
 
 
49
.SH CONNECTING TO AN LDAP SERVER
 
50
 
 
51
To create an ldap interface entity, we use the "ldap" command.
 
52
 
 
53
    ldap open foo foo.bar.com
 
54
 
 
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.
 
58
 
 
59
    ldap init foo foo.bar.com
 
60
 
 
61
Same as above, foo is created, but for "init", opening the connection is
 
62
deferred until we actually try to do something.
 
63
 
 
64
The init command also allows some optional values to be set for the connection.
 
65
Currently, the only useful option is \fBprotocol_version\fR which take a
 
66
single argument to specify to use LDAP protocol 2 or 3.  This may be required
 
67
when connecting to older LDAP server.
 
68
 
 
69
For the purposes of this example, we're going to assume that "foo" is the
 
70
command created by opening a connection using "ldap open".
 
71
 
 
72
.SH BINDING
 
73
 
 
74
After a connection is made to an LDAP server, an LDAP bind operation must
 
75
be performed before other operations can be attempted over the connection.
 
76
 
 
77
Both simple authentication and kerberos authentication are available.
 
78
LDAP version 3 supports many new "SSL"-style authentication and encryption
 
79
systems, which are not currently supported by the OpenLDAP v1.2 server, and
 
80
hence by this interface package.
 
81
 
 
82
Currently simple and kerberos-based authentication, are supported.
 
83
 
 
84
To use LDAP and still have reasonable security in a networked,
 
85
Internet/Intranet environment, secure shell can be used to setup
 
86
secure, encrypted connections between client machines and the LDAP
 
87
server, and between the LDAP server and any replica or slave servers
 
88
that might be used.
 
89
 
 
90
To perform the LDAP "bind" operation:
 
91
 
 
92
    foo bind simple dn password
 
93
 
 
94
    foo bind kerberos_ldap
 
95
    foo bind kerberos_dsa
 
96
    foo bind kerberos_both
 
97
 
 
98
It either returns nothing (success), or a Tcl error with appropriate error
 
99
text.
 
100
 
 
101
For example,
 
102
 
 
103
    foo bind simple "cn=Manager,o=NeoSoft Inc,c=us" "secret"
 
104
 
 
105
If you attempt to bind with one of the kerberos authentication types
 
106
described above and your LDAP library was not built with KERBEROS
 
107
defined, you will get an unknown auth type error.
 
108
 
 
109
To unbind an LDAP connection previously bound with "bind":
 
110
 
 
111
    foo unbind
 
112
 
 
113
Note that unbinding also deletes the command (\fBfoo\fR in this case).
 
114
Deleting the command has the same affect.
 
115
 
 
116
The ability of the library to callback to the client, enabling re-binding
 
117
while following referrals, is not currently supported.
 
118
 
 
119
.SH DELETING OBJECTS
 
120
 
 
121
To delete an object in the LDAP database, use
 
122
 
 
123
    foo delete dn
 
124
 
 
125
To rename an object to another relative distinguished name, use
 
126
 
 
127
    foo rename_rdn dn rdn
 
128
 
 
129
To rename an object to another relative distinguished name, leaving
 
130
the old entry as some kind of attribute (FIX: not sure if this is
 
131
right or how it works)
 
132
 
 
133
    foo modify_rdn dn rdn
 
134
 
 
135
 
 
136
.SH ADDING NEW OBJECTS
 
137
 
 
138
    foo add dn attributePairList
 
139
 
 
140
This creates a new distinguished name and defines zero or more attributes.
 
141
 
 
142
"attributePairList" is a list of key-value pairs, the same as would
 
143
be returned by "array get" if an array had been set up containing the
 
144
key-value pairs.
 
145
 
 
146
    foo add "cn=karl, ou=People, o=NeoSoft Inc, c=US" {cn karl ...}
 
147
 
 
148
Some directory servers and/or their client SDKs will automatically
 
149
add the leaf attribute value for you.
 
150
 
 
151
Here is a more precise description of how an attributePairList looks:
 
152
 
 
153
    {cn {karl {Karl Lehenbauer}} telephone 713-968-5800}
 
154
 
 
155
Note here that two cn values, "karl" and "Karl Lehenbauer", are added.
 
156
Is it an error to write:
 
157
 
 
158
    {cn {Karl Lehenbauer}}
 
159
 
 
160
Which adds two cn values, "Karl" and "Lehenbauer", when the intention
 
161
was to give a single cn value of "Karl Lehenbauer".  In real life, one
 
162
finds oneself making prodigous use of the \fBlist\fR command rather than
 
163
typing hard-coded lists.
 
164
 
 
165
We have noticed that the Netscape server will automatically add the
 
166
left-most rdn portion of the DN (ie. cn=karl), whereas the University
 
167
of Michigan and OpenLDAP 1.2 versions do not.
 
168
 
 
169
.SH ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES
 
170
 
 
171
You can have multiple values for a given attribute in an LDAP object.
 
172
These are represented in search results, through the Tcl interface,
 
173
as a list.
 
174
 
 
175
    foo add_attributes dn attributePairList
 
176
 
 
177
This adds key-value pairs to an existing DN.  If an attribute being
 
178
added already exists, the new value will be appended to the list.
 
179
If a particular value being added to an attribute already exists in
 
180
the object a Tcl error is raised.
 
181
 
 
182
    foo replace_attributes dn attributePairList
 
183
 
 
184
This replaces the specified attributes in an existing DN, leaving
 
185
unnamed ones untouched.  Any previous values for the supplied attributes
 
186
(if any) are discarded.
 
187
 
 
188
    foo delete_attributes dn attributePairList
 
189
 
 
190
This deletes attributes in the list.  If an attribute "foo" has the
 
191
value list {bar snap}, and you delete using the attributePairList "foo bar",
 
192
"foo" will still have "snap".
 
193
 
 
194
If you provide an empty string ("") for the value list,
 
195
the entire attribute will be deleted.
 
196
 
 
197
In Ldaptcl version 2.0, multiple operations may be combined into a single
 
198
transaction, ie. as in:
 
199
 
 
200
    foo add_attributes dn attributePairList replace attributePairList \
 
201
        delete attributePairList
 
202
 
 
203
.SH SEARCHING
 
204
 
 
205
The Tcl interface to searching takes a control array, which contains
 
206
a couple of mandatory key-value pairs, and can contain a number of
 
207
optional key-value pairs as well, for controlling the search, a
 
208
destination array, into which the specified attributes (or all attributes
 
209
of matching DNs if none are specified) and values are stored.
 
210
 
 
211
The "code" part is executed repeatedly, once for each DN matching the
 
212
search criteria.
 
213
 
 
214
.nf
 
215
    foo search controlArray destArray code
 
216
 
 
217
        Using data in the control array, a search is performed of the
 
218
        LDAP server opened when foo was created.  Possible elements
 
219
        of the control array are enumerated blow.
 
220
 
 
221
        controlArray(base) is the DN being searched from. (required)
 
222
 
 
223
        controlArray(filter) contains the search criteria. (required)
 
224
 
 
225
        controlArray(scope) must be "base", "one_level", or "subtree".
 
226
            If not specified, scope defaults to "subtree".
 
227
 
 
228
        controlArray(deref) must be "never", "search", "find", or "always"
 
229
            If not specified, deref defaults to "never"
 
230
 
 
231
        controlArray(attributes) is a list of attributes to be fetched.
 
232
            If not specified, all attributes are fetched.
 
233
 
 
234
        controlArray(timeout) a timeout value in seconds (may contain
 
235
            fractional values -- extremely very small values are useful
 
236
            for forcing timeout conditions to test timeouts).
 
237
.fi
 
238
 
 
239
For each matching record, destArray is populated with none,
 
240
some or all attribute-value pairs as determined by the request and
 
241
access control lists on the server.
 
242
 
 
243
Note:  There are some additional parameters that can be set, such as
 
244
how long the synchronous version of the routines should wait before
 
245
timing out, the interfaces for which are not available in the current
 
246
version.
 
247
 
 
248
.SH COMPARE
 
249
 
 
250
    foo compare dn attribute value
 
251
 
 
252
Interface to the ldap_compare_s() command.
 
253
Compares the value of \fIattribute\fR in the object at \fIdn\fR to the
 
254
\fIvalue\fR given in the command line.  Returns an error if \fIdn\fR
 
255
does not exist.  Otherwise, a
 
256
 
 
257
.SH CACHING (Note: Netscape clients do not have caching interfaces).
 
258
 
 
259
The UMich and OpenLDAP client libraries offers the client application fairly
 
260
fine-grained control of caching of results retrieved from searches,
 
261
offering significant performance improvement and reduced
 
262
network traffic.
 
263
 
 
264
By default, the cache is disabled.
 
265
 
 
266
To enable caching of data received from an LDAP connection,
 
267
 
 
268
    foo cache enable timeout maxmem
 
269
 
 
270
        ...where timeout is specified in seconds, and maxmem is the
 
271
        maximum memory to be used for caching, in bytes.
 
272
 
 
273
        If maxmem is 0, the cache size is restricted only by the timeout.
 
274
 
 
275
    foo cache disable
 
276
 
 
277
        ...temporarily inhibits use of the cache (while disabled, new requests
 
278
        are not cached and the cache is not checked when returning results).
 
279
 
 
280
        Disabling the cache does not delete its contents.
 
281
 
 
282
    foo cache destroy
 
283
 
 
284
        ...turns off caching and completely removes the cache from memory.
 
285
 
 
286
    foo cache flush
 
287
 
 
288
        ...deletes the entire cache contents, but does not affect
 
289
        whether or not the cache is being used.
 
290
 
 
291
    foo cache uncache dn
 
292
 
 
293
        ...removes from the cache all request results that make reference
 
294
        to the specified DN.
 
295
 
 
296
        This should be used, for example, after doing an add_attributes,
 
297
        delete_attributes, or replace_attributes (ldap_modify(3))
 
298
        involving the requested DN.  Generally this should not be needed,
 
299
        as the Tcl interface automatically performs this operation on
 
300
        any dn that is modified (add,replace,delete) while caching is
 
301
        enabled.
 
302
 
 
303
    foo cache no_errors
 
304
 
 
305
        ...suppresses caching of any requests that result in an error.
 
306
 
 
307
    foo cache size_errors
 
308
 
 
309
        ...suppresses caching of any requests that result in an error,
 
310
        except for requests resulting in "sizelimit exceeded", which
 
311
        are cached.  This is the default.
 
312
 
 
313
    foo cache all_errors
 
314
 
 
315
        ...enables caching of all requests, including those that result
 
316
        in errors.
 
317
 
 
318
.SH IMPLEMENTATION DECISIONS
 
319
 
 
320
Because we used the new "Tcl object" C interfaces, this package only works
 
321
with Tcl 8.0 or above.
 
322
 
 
323
This package interfaces with the University of Michigan LDAP protocol
 
324
package, version 3.3, and OpenLDAP version 1.2, both of which are
 
325
implementations of version 2 of the LDAP protocol.
 
326
 
 
327
Although an LDAP client (or server) could be written in native Tcl 8.0,
 
328
as Tcl 8.0 and above can do binary I/O, and Tcl 8 and above have strings
 
329
that are fully eight-bit clean, for a first implementation, to minimize
 
330
compatibility problems, we created a C interface to the UMich LDAP library.
 
331
 
 
332
A native Tcl implementation would be cool because we could bring the receiving
 
333
of messages into the normal Tcl event loop and run the LDAP interface fully
 
334
asynchronous.
 
335
 
 
336
This implementation is blocking, and blocking only.  That is to say that
 
337
the Tcl event loop is frozen while the ldap routines are waiting on data.
 
338
 
 
339
This could be fixed either by recoding all of the I/O in the LDAP library
 
340
to use Tcl's I/O system instead, or by simply coding the LDAP interface in
 
341
native Tcl, as mentioned above.
 
342
 
 
343
Another advantage of coding in high-level Tcl, of course, is that the
 
344
client would immediately be cross-platform to Windows and the Mac, as
 
345
well as Unix.
 
346
 
 
347
Binary data is not currently supported.  It will probably be trivial to
 
348
add, we just haven't dug into it yet.
 
349
 
 
350
 
 
351
.SH FOR MORE INFORMATION
 
352
 
 
353
This document principally describes how to use our Tcl interface to the
 
354
LDAP library works.
 
355
 
 
356
For more information on LDAP and the University of Michigan LDAP package,
 
357
please visit the website mentioned above.  The package includes substantial
 
358
documentation in the form of UNIX manual pages, a SLAPD/SLURPD guide
 
359
in Adobe Portable Document Format (pdf), and a number of Internet RFCs
 
360
related to LDAP services.
 
361
 
 
362
.SH AUTHORS
 
363
It was written by Karl Lehenbauer, of NeoSoft, Inc., in August and
 
364
September of 1997.  Ldap explode, and numerous bug fixes and extensions
 
365
by Randy Kunkee, also of NeoSoft, Inc., in 1998-1999.
 
366
 
 
367
.SH KEYWORDS
 
368
element, join, list, separator
 
369
.SH BUGS
 
370
The \fBldap init\fR syntax fails to return anything useful.  Use
 
371
\fBldap open\fR instead.
 
372
 
 
373
\fBPackage require Ldaptcl\fR won't work unless the ldap and lber libraries
 
374
are also shared, and ldaptcl.so is itself created with the correct flags
 
375
(eg. -R for Solaris).  In short there's a lot of details to make this part
 
376
work, but it should work out of the box for Solaris.  Other systems may
 
377
require that LD_LIBRARY_PATH or other appropraite environment variables
 
378
be set at build and/or runtime.
 
379
 
 
380
An asynchronous interface should be provided with callbacks.
 
381
 
 
382
We have never tested Kerberos authentication.
 
383
 
 
384
It does not tolerate some illegal operations very well.
 
385
 
 
386
It is possible to create empty attributes, ie. attributes which are present
 
387
but have no value.  This is done by deleting the attribute values rather
 
388
than, eg. "foo delete_attributes dn {telephone {}}" which would delete
 
389
the telephone attribute altogether.  A search for presence of the attribute
 
390
may return an object, and yet it may have no value.  This interface presents
 
391
such an object as not having the attribute at all (ie. you cannot tell).
 
392
The Netscape SDK does this for you, so this makes the behavior consistent
 
393
when using UMICH_LDAP.
 
394
 
 
395
\--enable-netscape configuration support has not been tested and probably
 
396
has bugs.