Various operations on
directories are supported after loading the external
module. Only after loading the module, the
extension command becomes accessible.
Example for Tcl :
package require Ldap
or, in Python ,
from ldap import *
The next step is usually the establishment of a connection ( bind ) to a known LDAP server. In many cases credentials are required for a successful bind with a DN containing a user name. After a completed bind , a handle or reference is returned. This handle can be used for further operations, such as information retrieval, until the connection is closed by an unbind command.
The general syntax of the
command follows the usual
set lhandle [ldap bind $host $port $binddn $passwd]
ldap unbind $lhandle
The LDAP module currently only supports synchronous operations.
This is the list of subcommands:
Open a connection to an LDAP server and return the connection handle. Only the host parameter is required. If no port is specified, or an empty string, the default LDAP port (389) is used. If no distinguished name for binding is supplied, or an empty string, an anonymous bind is attempted. If an access control password is required, it may be supplied as last parameter.
This command can be used to add, replace or delete one or more attributes of a DN. The attribute list is a standard Tcl list or Python tuple, where each attribute is a list element. The list elements must be of the form attribute=value , or simply attribute for deletions. Optionally, they may be prefixed by one of the characters “+” (add attribute), “=” (replace attribute, or create new if not existing), and “-” (delete attribute). The implicit default is “=”. It is possible to add multiple instances of attributes, such as a set of e-mail addresses in the form
command is a variant of this command - the only difference is that the default modification mode is
, corresponding to am implicit “+” prefix instead of “=”.
The optional scope argument may be
or an empty string (the default setting, in
you can also use
(search only the base object),
(search one level of sub-objects), or
(can be shortened to
, search all sub-objects of the base object).
The filter parameter is a standard
filter, which can be used to select subsets of directory entries. An empty string in this position (or
), or omitting the parameter, disables filtering.
Finally, the last parameter is the set of attributes which should be returned. If it is omitted, or an empty string (or
), all attributes of each matched entry are returned. If a requested attribute is not present in a matching record, it is silently omitted from the result list.
If no errors occurred, the result is a triply nested list. The outermost list contains one element for each entry. If a maximum number of responses was set to a positive value (
configuration parameter, see
command), the maximum number of list elements is defined by this parameter. Each outer list element is itself a list. The middle lists contain one element for each returned attribute. Each of these is formatted as another sublist with
list elements. The attributes are returned in the order they were specified, provided that they are found in the returned set. If requested attributes are not present, they are silently omitted from the result list.
The filter argument1 is a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified using a prefix notation according to the following BNF :
<filter> ::= '(' <filtercomp> ')' <filtercomp> ::= <and> | <or> | <not> | <simple><and> ::= '&' <filterlist><or> ::= '|' <filterlist><not> ::= '!' <filter><filterlist> ::= <filter> | <filter> <filterlist><simple> ::= <attributetype> <filtertype> <attributevalue><filtertype> ::= '=' | '~=' | '<=' | '>='
The '~=' construct is used to specify approximate matching. The representation for
are as described in RFC 2254. In addition,
can be a single * to achieve an attribute existence test, or can contain text and *'s interspersed to achieve substring matching.
For example, the filter "mail=*" finds any entries that have a mail attribute. The filter "email@example.com" will find any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash '\' character. See RFC 2254 for a more complete description of allowable filters.
The first variant unbinds or closes (these are equivalent commands) a specific set of LDAP connections. All resources associated with the connection are freed, and the handles invalidated. However, they may later be reassigned to new connections.
Perform a basic (
) user/access verification. The first variant uses an existing handle and attempts to re-bind it with a different distinguished bind name. The connection remains bound to the new address and DN.
The second variant temporarily creates a new
connection and attempts to bind. The parameters have the same meaning as in the
command. The status is saved and then the connection is immediately closed. No persistent
object is created.