Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 395 insertions, 0 deletions

diff --git a/contrib/ldaptcl/ldap.n b/contrib/ldaptcl/ldap.n
new file mode 100644
index 0000000..ec75e3d
--- /dev/null
+++ b/contrib/ldaptcl/ldap.n
@@ -0,0 +1,395 @@
+'\"
+'\" Copyright (c) 1998 NeoSoft, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH ldap n "" Ldap "Ldap Tcl Extension"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+ldap \- connect to and query an LDAP server
+.SH SYNOPSIS
+\fBldap \fBopen \fR \fIcommand\fR \fIhostlist\fR
+.br
+\fBldap \fBinit \fR \fIcommand\fR \fIhostlist\fR ?protocol_version [2|3]?
+.br
+\fBldap \fBexplode ?-nonames|-list?\fR \fIdn\fR
+.br
+\fIcommand \fBsubcommand \fIoptions ...\fR
+.BE
+
+.SH OVERVIEW
+.PP
+A new command by the name of \fIcommand\fR will be created to access
+the LDAP database at \fIhostlist\fR.  \fIhostlist\fR may contain elements
+of the format \fBhost:port\fR if a port other than the default LDAP port
+of 389 is required.  The LDAP library will attempt to connect to each
+host in turn until it succeeds or exhausts the list.
+.PP
+The \fBexplode\fR form provides a means (via ldap_explode(3)) to explode a DN
+into its component parts.  \fB-nonames\fR strips off the attribute names,
+and -list returns a list suitable for \fBarray set\fR.
+.PP
+Finally, the last form, described in more detail below, refers generically
+to how the command created by the first two examples is used.
+.SH DESCRIPTION
+
+The Lightweight Directory Access Protocol provides TCP/IP access to
+X.500 directory services and/or to a stand-alone LDAP server.
+
+This code provides a Tcl interface to the
+Lightweight Directory Access Protocol package using the Netscape
+Software Development Kit.  It can also be used with the freely
+redistributable University of 
+Michigan (http://www.umich.edu/~rsug/ldap) version by defining the
+UMICH_LDAP macro during compilation.
+
+.SH CONNECTING TO AN LDAP SERVER
+
+To create an ldap interface entity, we use the "ldap" command.
+
+    ldap open foo foo.bar.com
+
+This opens a connection to a LDAP server on foo.bar.com, and makes
+a new Tcl command, foo, through which we will manipulate the interface
+and make queries to the remote LDAP server.
+
+    ldap init foo foo.bar.com
+
+Same as above, foo is created, but for "init", opening the connection is 
+deferred until we actually try to do something.
+
+The init command also allows some optional values to be set for the connection.
+Currently, the only useful option is \fBprotocol_version\fR which take a
+single argument to specify to use LDAP protocol 2 or 3.  This may be required
+when connecting to older LDAP server.
+
+For the purposes of this example, we're going to assume that "foo" is the
+command created by opening a connection using "ldap open".
+
+.SH BINDING
+
+After a connection is made to an LDAP server, an LDAP bind operation must
+be performed before other operations can be attempted over the connection.
+
+Both simple authentication and kerberos authentication are available.
+LDAP version 3 supports many new "SSL"-style authentication and encryption
+systems, which are not currently supported by the OpenLDAP v1.2 server, and
+hence by this interface package.
+
+Currently simple and kerberos-based authentication, are supported.
+
+To use LDAP and still have reasonable security in a networked, 
+Internet/Intranet environment, secure shell can be used to setup
+secure, encrypted connections between client machines and the LDAP
+server, and between all LDAP nodes that might be used.
+
+To perform the LDAP "bind" operation:
+
+    foo bind simple dn password
+
+    foo bind kerberos_ldap
+    foo bind kerberos_dsa
+    foo bind kerberos_both
+
+It either returns nothing (success), or a Tcl error with appropriate error
+text.
+
+For example,
+
+    foo bind simple "cn=Manager,o=NeoSoft Inc,c=us" "secret"
+
+If you attempt to bind with one of the kerberos authentication types
+described above and your LDAP library was not built with KERBEROS
+defined, you will get an unknown auth type error.
+
+To unbind an LDAP connection previously bound with "bind":
+
+    foo unbind
+
+Note that unbinding also deletes the command (\fBfoo\fR in this case).
+Deleting the command has the same affect.
+
+The ability of the library to callback to the client, enabling re-binding
+while following referrals, is not currently supported.
+
+.SH DELETING OBJECTS
+
+To delete an object in the LDAP database, use
+
+    foo delete dn
+
+To rename an object to another relative distinguished name, use
+
+    foo rename_rdn dn rdn
+
+To rename an object to another relative distinguished name, leaving
+the old entry as some kind of attribute (FIX: not sure if this is
+right or how it works)
+
+    foo modify_rdn dn rdn
+
+
+.SH ADDING NEW OBJECTS
+
+    foo add dn attributePairList
+
+This creates a new distinguished name and defines zero or more attributes.
+
+"attributePairList" is a list of key-value pairs, the same as would
+be returned by "array get" if an array had been set up containing the
+key-value pairs.
+
+    foo add "cn=karl, ou=People, o=NeoSoft Inc, c=US" {cn karl ...}
+
+Some directory servers and/or their client SDKs will automatically
+add the leaf attribute value for you.
+
+Here is a more precise description of how an attributePairList looks:
+
+    {cn {karl {Karl Lehenbauer}} telephone 713-968-5800}
+
+Note here that two cn values, "karl" and "Karl Lehenbauer", are added.
+Is it an error to write:
+
+    {cn {Karl Lehenbauer}}
+
+Which adds two cn values, "Karl" and "Lehenbauer", when the intention
+was to give a single cn value of "Karl Lehenbauer".  In real life, one
+finds oneself making prodigous use of the \fBlist\fR command rather than
+typing hard-coded lists.
+
+We have noticed that the Netscape server will automatically add the
+left-most rdn portion of the DN (ie. cn=karl), whereas the University
+of Michigan and OpenLDAP 1.2 versions do not.
+
+.SH ADDING, DELETING, AND REPLACING OBJECT ATTRIBUTES
+
+You can have multiple values for a given attribute in an LDAP object.
+These are represented in search results, through the Tcl interface,
+as a list.
+
+    foo add_attributes dn attributePairList
+
+This adds key-value pairs to an existing DN.  If an attribute being
+added already exists, the new value will be appended to the list.
+If a particular value being added to an attribute already exists in
+the object a Tcl error is raised.
+
+    foo replace_attributes dn attributePairList
+
+This replaces the specified attributes in an existing DN, leaving
+unnamed ones untouched.  Any previous values for the supplied attributes
+(if any) are discarded.
+
+    foo delete_attributes dn attributePairList
+
+This deletes attributes in the list.  If an attribute "foo" has the
+value list {bar snap}, and you delete using the attributePairList "foo bar",
+"foo" will still have "snap".
+
+If you provide an empty string ("") for the value list,
+the entire attribute will be deleted.
+
+In Ldaptcl version 2.0, multiple operations may be combined into a single
+transaction, ie. as in:
+
+    foo add_attributes dn attributePairList replace attributePairList \
+	delete attributePairList
+
+.SH SEARCHING
+
+The Tcl interface to searching takes a control array, which contains
+a couple of mandatory key-value pairs, and can contain a number of
+optional key-value pairs as well, for controlling the search, a
+destination array, into which the specified attributes (or all attributes
+of matching DNs if none are specified) and values are stored.
+
+The "code" part is executed repeatedly, once for each DN matching the
+search criteria.
+
+.nf
+    foo search controlArray destArray code
+
+	Using data in the control array, a search is performed of the
+	LDAP server opened when foo was created.  Possible elements
+	of the control array are enumerated blow.
+
+	controlArray(base) is the DN being searched from. (required)
+
+	controlArray(filter) contains the search criteria. (required)
+
+	controlArray(scope) must be "base", "one_level", or "subtree".
+	    If not specified, scope defaults to "subtree".
+
+	controlArray(deref) must be "never", "search", "find", or "always"
+	    If not specified, deref defaults to "never"
+
+	controlArray(attributes) is a list of attributes to be fetched.
+	    If not specified, all attributes are fetched.
+
+	controlArray(timeout) a timeout value in seconds (may contain
+	    fractional values -- extremely very small values are useful
+	    for forcing timeout conditions to test timeouts).
+.fi
+
+For each matching record, destArray is populated with none,
+some or all attribute-value pairs as determined by the request and
+access control lists on the server.
+
+Note:  There are some additional parameters that can be set, such as
+how long the synchronous version of the routines should wait before
+timing out, the interfaces for which are not available in the current
+version.
+
+.SH COMPARE
+
+    foo compare dn attribute value
+
+Interface to the ldap_compare_s() command.
+Compares the value of \fIattribute\fR in the object at \fIdn\fR to the
+\fIvalue\fR given in the command line.  Returns an error if \fIdn\fR
+does not exist.  Otherwise, a 
+
+.SH CACHING (Note: Netscape clients do not have caching interfaces).
+
+The UMich and OpenLDAP client libraries offers the client application fairly
+fine-grained control of caching of results retrieved from searches, 
+offering significant performance improvement and reduced
+network traffic.
+
+By default, the cache is disabled.
+
+To enable caching of data received from an LDAP connection,
+
+    foo cache enable timeout maxmem
+
+	...where timeout is specified in seconds, and maxmem is the
+	maximum memory to be used for caching, in bytes.
+
+	If maxmem is 0, the cache size is restricted only by the timeout.
+
+    foo cache disable
+
+	...temporarily inhibits use of the cache (while disabled, new requests
+	are not cached and the cache is not checked when returning results).
+
+	Disabling the cache does not delete its contents.
+
+    foo cache destroy
+
+	...turns off caching and completely removes the cache from memory.
+
+    foo cache flush
+
+	...deletes the entire cache contents, but does not affect
+	whether or not the cache is being used.
+
+    foo cache uncache dn
+
+	...removes from the cache all request results that make reference 
+	to the specified DN.
+
+	This should be used, for example, after doing an add_attributes,
+	delete_attributes, or replace_attributes (ldap_modify(3)) 
+	involving the requested DN.  Generally this should not be needed,
+	as the Tcl interface automatically performs this operation on
+	any dn that is modified (add,replace,delete) while caching is
+	enabled.
+
+    foo cache no_errors
+
+	...suppresses caching of any requests that result in an error.
+
+    foo cache size_errors
+
+	...suppresses caching of any requests that result in an error,
+	except for requests resulting in "sizelimit exceeded", which 
+	are cached.  This is the default.
+
+    foo cache all_errors
+
+        ...enables caching of all requests, including those that result
+	in errors.
+
+.SH IMPLEMENTATION DECISIONS
+
+Because we used the new "Tcl object" C interfaces, this package only works
+with Tcl 8.0 or above.
+
+This package interfaces with the University of Michigan LDAP protocol
+package, version 3.3, and OpenLDAP version 1.2, both of which are
+implementations of version 2 of the LDAP protocol.
+
+Although an LDAP client (or server) could be written in native Tcl 8.0,
+as Tcl 8.0 and above can do binary I/O, and Tcl 8 and above have strings 
+that are fully eight-bit clean, for a first implementation, to minimize 
+compatibility problems, we created a C interface to the UMich LDAP library.
+
+A native Tcl implementation would be cool because we could bring the receiving
+of messages into the normal Tcl event loop and run the LDAP interface fully
+asynchronous.
+
+This implementation is blocking, and blocking only.  That is to say that
+the Tcl event loop is frozen while the ldap routines are waiting on data.
+
+This could be fixed either by recoding all of the I/O in the LDAP library
+to use Tcl's I/O system instead, or by simply coding the LDAP interface in
+native Tcl, as mentioned above.
+
+Another advantage of coding in high-level Tcl, of course, is that the
+client would immediately be cross-platform to Windows and the Mac, as
+well as Unix.
+
+Binary data is not currently supported.  It will probably be trivial to 
+add, we just haven't dug into it yet.
+
+
+.SH FOR MORE INFORMATION
+
+This document principally describes how to use our Tcl interface to the 
+LDAP library works.
+
+For more information on LDAP and the University of Michigan LDAP package,
+please visit the website mentioned above.  The package includes substantial
+documentation in the form of UNIX manual pages, a SLAPD/SLURPD guide
+in Adobe Portable Document Format (pdf), and a number of Internet RFCs
+related to LDAP services.
+
+.SH AUTHORS
+It was written by Karl Lehenbauer, of NeoSoft, Inc., in August and
+September of 1997.  Ldap explode, and numerous bug fixes and extensions
+by Randy Kunkee, also of NeoSoft, Inc., in 1998-1999.
+
+.SH KEYWORDS
+element, join, list, separator
+.SH BUGS
+The \fBldap init\fR syntax fails to return anything useful.  Use
+\fBldap open\fR instead.
+
+\fBPackage require Ldaptcl\fR won't work unless the ldap and lber libraries
+are also shared, and ldaptcl.so is itself created with the correct flags
+(eg. -R for Solaris).  In short there's a lot of details to make this part
+work, but it should work out of the box for Solaris.  Other systems may
+require that LD_LIBRARY_PATH or other appropriate environment variables
+be set at build and/or runtime.
+
+An asynchronous interface should be provided with callbacks.
+
+We have never tested Kerberos authentication.
+
+It does not tolerate some illegal operations very well.
+
+It is possible to create empty attributes, ie. attributes which are present
+but have no value.  This is done by deleting the attribute values rather
+than, eg. "foo delete_attributes dn {telephone {}}" which would delete
+the telephone attribute altogether.  A search for presence of the attribute
+may return an object, and yet it may have no value.  This interface presents
+such an object as not having the attribute at all (ie. you cannot tell).
+The Netscape SDK does this for you, so this makes the behavior consistent
+when using UMICH_LDAP.
+
+\--enable-netscape configuration support has not been tested and probably
+has bugs.