The ldap Module

Various operations on LDAP directories are supported after loading the external Ldap Tcl or Python module. Only after loading the module, the ldap 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 ldap command follows the usual command/subcommand/handle/ parameter s syntax.


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:

ldap add

ldap add ldhandle dn attribute_list

Add one or more attributes to an existing DN. Other than that the default mode is LDAP_MOD_ADD , this command is identical to ldap replace .

The command returns the original handle or reference.

ldap addrdn

ldap addrdn ldhandle dn newrdn

Add a new relative DN to an existing LDAP directory identified by the base DN.

The command returns the original handle or reference.

ldap bind

ldap bind host ?port? ?bindDN? ?password?
ldap open host ?port? ?bindDN? ?password?

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.

The open command alternative is simply an alias intended to provide the standard command nomenclature for opening connections or files.


set lh [ldap bind $host 389 “cn=mr_x,cn=users,dc=chemcodes,dc=com” $themagicword]

ldap close

This is an alias for ldap unbind .

ldap delete

ldap delete ldhandle ?dn?...

This command deletes one or more DNs from the current LDAP server.

ldap get

ldap get ldhandle attribute

Query status information about the LDAP connection. Currently, the following attributes can be queried:


set tl [ldap get $ldhandle timelimit]

ldap list

ldap list ?pattern?

List all currently open LDAP connections. A list of the connection handles is returned Optionally, the handles, which are of the form ldap%d , may be filtered by a string pattern.


ldap list

ldap ref


Python -only method to get a reference of the LDAP object from its handle.

ldap replace

ldap replace ldhandle dn attribute_list

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

set alist [list “” “”]

The ldap add command is a variant of this command - the only difference is that the default modification mode is LDAP_MOD_ADD instead of LDAP_MOD_REPLACE , corresponding to am implicit “+” prefix instead of “=”.

ldap update is a command alias.

The command returns the original handle or reference.


ldap replace $ldhandle “cn=wdi,cn=users,dc=chemcodes,dc=com” \ “”

ldap replacerdn

ldap replacerdn ldhandle dn newrdn

Replace a DN in an LDAP directory. The old DN is deleted, and replaced by the new DN, which may be specified relative to the old.

ldap updaterdn is a command alias.

The command returns the original handle or reference.

ldap search

ldap search ldhandle baseDN ?scope? ?getdn? ?filter? ?attributelist?,?scope=?,?getdn=?,?filter=?,?attributes=?)

Query an LDAP server for information. Besides an active LDAP connection, the minimal argument set is only the base DB, the root from where the query should start on the connected server.

The optional scope argument may be default or an empty string (the default setting, in Python you can also use None ), base (search only the base object), one or level (search one level of sub-objects), or subtree (can be shortened to sub , search all sub-objects of the base object).

The getdn parameter is a boolean flag. If it is set, the first element of each response sublist is the DN of the entry. By default, only the attribute data is returned.

The filter parameter is a standard LDAP filter, which can be used to select subsets of directory entries. An empty string in this position (or None for Python ), 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 None for Python ), 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 ( sizelimit configuration parameter, see ldap set 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 attribute and value 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 command currently does support the retrieval of binary data.


ldap search $ldhandle “cn=users,dc=chemcodes,dc=com” one 0 {} [list mail phone]

returns a nested list of addresses, in the format

{{mail user1@addr1} {phone xxx-100}} {{mail user2@addr2} {phone xxx-105}}...

if both the mail and phone attributes are present.

The retrieval of the e-mail address of user wdi may be achieved either by using a filter, or a more specific DN:

ldap search $ldhandle “cn=users,dc=chemcodes,dc=com” one 0 cn=wdi “mail phone”
ldap search $ldhandle “cn=wdi,cn=users,dc=chemcodes,dc=com” one 0 {} “mail phone”

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 <attributetype> and <attributevalue> are as described in RFC 2254. In addition, <attributevalue> 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 "mail=*" 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.

ldap set

ldap set ldhandle ?attribute value?...
ldap set ldhandle dict
l.attribute = value
l[attribute] = value

Set one or more attributes for an LDAP connection. Currently, the following attributes can be set:

The command returns the original handle or reference.


ldap set $ldhandle sizelimit 5 timelimit 500

ldap unbind

ldap unbind ldhandle ?ldhandle?...
ldap close ldhandle ?ldhandle?...
ldap unbind all
ldap close all

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.

The second alternative closes all currently opened LDAP connections.

The command returns the number of closed connections.


ldap close all

ldap verify

ldap verify ldhandle bindDN password
ldap verify host port bindDN password

Perform a basic ( LDAP_AUTH_SIMPLE ) 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 LDAP connection and attempts to bind. The parameters have the same meaning as in the ldap bind command. The status is saved and then the connection is immediately closed. No persistent LDAP object is created.

This command returns boolean 1 for a successful bind, and 0 for failure.


ldap verify $host ““ “dn=wdi,dn=users,dc=chemcodes,dc=com” $mypwd

1. Description of filters copied from the OpenLDAP man page for ldap_search(3)