ldap(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

ldap(n) — the LDAP client, bestie edition 💅

okay so this is ldap, a manual page from the LDAP client corner of the Tcl universe, and I am so excited to walk you through it. grab a boba, we're going in 🧋✨

✨ NAME ✨

ldap — it's an LDAP client. that's it. that's the name. short, sweet, iconic. 👑

🌸 SYNOPSIS 🌸

okay bestie, here's the whole shape of it up front. no cap, it's a lot of commands, but they're all giving "very organized, very demure."

package require Tcl 8.5 9

package require ldap ?1.10.2?

::ldap::connect host ?port?

::ldap::tlsoptions reset

::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...

::ldap::secure_connect host ?port?

::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?

::ldap::disconnect handle

::ldap::starttls handle

::ldap::starttls  handle  ?cafile?  ?certfile?  ?keyfile?  ?verify_cert?
?sni_servername?

::ldap::bind handle ?name? ?password?

::ldap::bindSASL handle ?name? ?password?

::ldap::unbind handle

::ldap::search handle baseObject filterString attributes options

::ldap::searchInit handle baseObject filterString attributes options

::ldap::searchNext handle

::ldap::searchEnd handle

::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?

::ldap::modifyMulti   handle   dn   attrValToReplace   ?attrValToDelete?
?attrValToAdd?

::ldap::add handle dn attrValueTuples

::ldap::addMulti handle dn attrValueTuples

::ldap::delete handle dn

::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?

::ldap::info ip handle

::ldap::info bound handle

::ldap::info bounduser handle

::ldap::info connections

::ldap::info tls handle

::ldap::info tlsstatus handle

::ldap::info saslmechanisms handle

::ldap::info control handle

::ldap::info extensions extensions

::ldap::info whoami handle

💡 little heads up: those ?question mark? bits mean "optional, bestie." the required stuff has no question marks and no chill.

💖 DESCRIPTION 💖

so the ldap package is a Tcl-only client library for the LDAPv3 protocol, exactly as specified in RFC 4511 (http://www.rfc-editor.org/rfc/rfc4511.txt). iykyk. ✨

the way it works: it opens the standard (or secure, if you're fancy) LDAP socket on the server, and then hands you a Tcl API so you can talk to the LDAP protocol commands. it's giving translator, but make it unix. 🦋

and here's the part you cannot skip: all server errors are returned as Tcl errors (thrown), which means you have to catch them with the Tcl catch command. fr fr. no try/catch-avoidance behavior here. 🫶

🔐 TLS SECURITY CONSIDERATIONS 🔐

this package uses the TLS package to handle the security for LDAPS connections. slay. 🎀

but — and this is the important part — policy decisions like which set of protocols to support and which ciphers to use are not the responsibility of TLS, and not the responsibility of this package either. those decisions belong to whichever application is using the package, and they're probably going to be influenced by the set of servers that application is going to talk to as well. so like, read the room (and the deployment). 💀

for example — and this is a big one — in light of the recent POODLE attack [http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html] discovered by Google, many servers will disable support for the SSLv3 protocol. to handle that change, the applications using TLS must be patched — not this package, and not TLS itself. periodt. such a patch may be as simple as generally activating tls1 support, as shown in the example below. 👇

ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol

... your own application code ...

🚨 bestie note: that comment is verbatim and so is that line. type it exactly. do not freestyle the TLS settings, i am begging. 🙈

🫶 COMMANDS 🫶

every single one, in order, no skipping. let's get into it. 💅

`::ldap::connect host ?port?`

opens a LDAPv3 connection to the specified host, at the given port, and returns a token for the connection. that token is the handle argument for all the other commands. if you don't specify a port, it defaults to 389. 🌸

the command blocks until the connection has been established, or until establishment definitely failed. so yeah, it waits. it's not ghosting you, it's just doing its job. 💀

`::ldap::tlsoptions reset`

this one resets TLS options back to default values, and it returns the set of options. 💖

⚠️ using this command is incompatible with the obsolete form of ::ldap::secure_connect and ::ldap_starttls. yes, that second one is spelled exactly like that. keep it.

`::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...`

this command adds one or more options to some value, and you can use it more than one time to add options in several steps. very build-a-bear of it. 🧸

a complete description of options may be found in the tls package documentation. valid options and values are:

-cadir directory — provide the directory containing the CA certificates. no default.
-cafile file — provide the CA file. no default.
-cipher string — provide the cipher suites to use. no default.
-dhparams file — provide a Diffie-Hellman parameters file. no default.
-request boolean — request a certificate from peer during SSL handshake. default: true.
-require boolean — require a valid certificate from peer during SSL handshake. if this is set to true then -request must also be set to true. default: false.
-servername host — only available if the OpenSSL library the TLS package is linked against supports the TLS hostname extension for 'Server Name Indication' (SNI). use it to name the logical host we are talking to and expecting a certificate for. no default.
-ssl2 bool — enable use of SSL v2. default: false.
-ssl3 bool — enable use of SSL v3. default: false.
-tls1 bool — enable use of TLS v1. default: true.
-tls1.1 bool — enable use of TLS v1.1. default: true.
-tls1.2 bool — enable use of TLS v1.2. default: true.

this command also returns the current set of TLS options and values. in particular, you can use this command with no arguments at all to just get the current set of options. main character energy: it both does the thing and tells you about the thing. 👑

⚠️ using this command is incompatible with the obsolete form of ::ldap::secure_connect and ::ldap_starttls (see below).

`::ldap::secure_connect host ?port?`

literally like ::ldap::connect, except the connection it makes is secured by SSL. the port defaults to 636. 🔒

this command depends on the availability of the package TLS, which is a SSL binding for Tcl. if TLS is not available, then this command will fail. no TLS, no secure connection, that's the rule. 💀

TLS options are specified with ::ldap::tlsoptions.

the command blocks until the connection has been established, or until establishment definitely failed.

`::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?`

🚨 Note: this form of the command is deprecated, since TLS options had to be specified with a combination of parameters to this command (verify_cert and sni_servername) and arguments to ::tls::init (from package tls), for example to set up defaults for trusted certificates. prefer the above form (without the verify_cert and sni_servername parameters) and set TLS options with ::ldap::tlsoptions.

if verify_cert is set to 1 — which is the default — this checks the server certificate against the known hosts. if sni_servername is set, the given hostname is used as the hostname for Server Name Indication in the TLS handshake. 🦋

use ::tls::init to set up defaults for trusted certificates.

TLS supports different protocol levels. in common use are versions 1.0, 1.1 and 1.2. by default all those versions are offered. if you need to modify the acceptable protocols, you can change the ::ldap::tlsProtocols list (deprecated).

`::ldap::disconnect handle`

closes the ldap connection referred to by the token handle. returns the empty string as its result. polite. tidy. we love a clean exit. 💖

`::ldap::starttls handle`

start TLS negotiation on the connection denoted by handle, with TLS parameters set with ::ldap::tlsoptions. that's the whole vibe. ✨

`::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert? ?sni_servername?`

🚨 Note: this form of the command is deprecated, since TLS options had to be specified with a combination of parameters to this command (cafile, certfile, keyfile, verify_cert and sni_servername) and arguments to ::tls::init (from package tls). prefer the above form (without specific TLS arguments) and set TLS options with ::ldap::tlsoptions.

start TLS negotiation on the connection denoted by handle. you need to set at least the cafile argument to a file with trusted certificates, if verify_cert is 1, which is the default. 🙈

the sni_servername can be used to signal a different hostname during the TLS handshake. the announced protocols are determined in the same way as ::ldap::secure_connect. you can specify a TLS client certificate with the certfile and keyfile options. 🎀

`::ldap::bind handle ?name? ?password?`

this command authenticates the ldap connection referred to by the token in handle, with a user name and associated password. it blocks until a response from the ldap server arrives. its result is the empty string. 💅

both name and passwd default to the empty string if they are not specified. by leaving out name and passwd you can make an anonymous bind to the ldap server. and you can issue ::ldap::bind again to bind with different credentials — it's giving "glow up, new identity." 🌈

`::ldap::bindSASL handle ?name? ?password?`

this command uses SASL authentication mechanisms to do a multistage bind. otherwise it's identical to the standard ::ldap::bind.

⚠️ this feature is currently experimental and subject to change. bestie, do not build your whole empire on it yet. 💀

see the documentation for the SASL and the "SASL.txt" in the tcllib CVS repository for details on how to set up and use SASL with openldap. 📚

`::ldap::unbind handle`

this command asks the ldap server to release the last bind done for the connection referred to by the token in handle. 🫶

⚠️ the handle is invalid after the unbind, as the server closes the connection. so this is effectively just a more polite disconnect operation. it's not goodbye, it's "i'll see myself out." 🚪✨

`::ldap::search handle baseObject filterString attributes options`

this command performs a LDAP search below the baseObject tree using a complex LDAP search expression filterString, and returns the specified attributes of all matching objects (DNs). if the list of attributes was empty, then all attributes are returned. the command blocks until it has received all results. 👑

the valid options are identical to the options listed for ::ldap::searchInit.

an example of a search expression is

set filterString "|(cn=Linus*)(sn=Torvalds*)"

the return value of the command is a list of nested dictionaries. the first level keys are object identifiers (DNs), second level keys are attribute names. in other words, it is in the form

okay and that's where we're pausing bestie, because the rest of this page is part 2 energy and we are not skipping it. see you in the next one 💖🦋

…so the whole thing stacks up like this:

{dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...

`::ldap::searchInit` 💅

::ldap::searchInit handle baseObject filterString attributes options

Okay bestie, this one kicks off a LDAP search under the baseObject tree using a fancy complex LDAP search expression called filterString. The search grabs the attributes you asked for off every matching object (those are the DNs). ✨

Important vibe check though: this command only starts the search. It doesn't hand you results. To actually go get them you use ::ldap::searchNext. And you can dip out at literally any time with ::ldap::searchEnd — which politely tells the server "no more results pls" by sending an ABANDON message and then tidies up the internal state of the search. 🧹

Only one ::ldap::search can be active at a time. And yeah, that counts the introspection commands ::ldap::info saslmechanisms, ldap::info control and ldap::info extensions, because those run a search internally too. So no double-dipping. 🙈

Error responses from the server — you know, the ones that happen because of wrong arguments or similar stuff — come back with the first ::ldap::searchNext call, so that's where you check for them and deal with them. Not before. 👑

If the list of requested attributes is empty, literally all attributes get returned. Slay, but also watch out, that's a lot of data. 🌸

The options parameter is the search options, shaped like this:

{-option1 value1 -option2 value2 ... }

And here's the options menu, babes:

-scope base one sub — controls the scope of the search: base, one, or sub, for a base object search, a one-level search, or a subtree search. Default is sub. 🌈
-derefaliases never search find always — controls how alias dereferencing goes down. One of never, always, search, or find: aliases are never dereferenced, always dereferenced, dereferenced when searching, or dereferenced only when locating the base object for the search. Default is to never dereference aliases. 💅
-sizelimit num — the max number of entries to return in a search. If it's 0, no limit is enforced. The server may enforce its own configuration-dependent sizelimit, which could be lower than the one you set here. Default is 0, no limit. 🫶
-timelimit seconds — asks the server to use a timelimit of seconds for the search. Zero means no limit. Default is 0, no limit. ⏳
-attrsonly boolean — if set to 1, only the attribute names show up in the search result, not the values. Default is to retrieve both names and values. 👑
-referencevar varname — if set, the search result reference LDAPURIs (if there are any) get returned in the given variable. Then you, the caller, can decide whether to follow those references and go query other LDAP servers for more results. 🦋

`::ldap::searchNext` ✨

::ldap::searchNext handle

This returns the next entry from a LDAP search that ::ldap::searchInit started. It only comes back once a new result has been received, or when there are no further results left — but it's thoughtful enough to keep the event loop alive while it waits. 💖

The entry it hands you is a list with two elements: first the DN of the entry, second the list of attributes and values, formatted like:

dn {attr1 {val11 val12 ...} attr2 {val21...} ...}

At the end of the search, ::ldap::searchNext returns an empty list. That's your cue that it's over, bestie. 🎀

`::ldap::searchEnd` 🌸

::ldap::searchEnd handle

This terminates a LDAP search that ::ldap::searchInit started. It also cleans up the internal state, so a fresh search can be initiated afterwards. ✨

If the client hasn't received all the results yet, it sends an ABANDON message to let the server know no further results for the previous search should be sent. So considerate. 🫶

`::ldap::modify` 💅

::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?

This modifies the object dn on the ldap server you're connected to via handle. It replaces attributes with new values, deletes attributes, and adds new attributes with new values. 🔥

All arguments are dictionaries mapping attribute names to values. The optional arguments default to the empty dictionary, which means no attributes get deleted and none get added. Simple as that.

dictionary attrValToReplace (in) — no attributes will be changed if this argument is empty. The dictionary contains the new attributes and their values. They replace all attributes known to the object. 👑
dictionary attrToDelete (in) — no attributes will be deleted if this argument is empty. The dictionary values are restrictions on the deletion. An attribute listed here gets deleted if and only if its current value at the server matches the value specified in the dictionary, or if the value in the dictionary is the empty string. 💀
dictionary attrValToAdd (in) — no attributes will be added if this argument is empty. The dictionary values are the values for the new attributes. 🦋

The command blocks until all modifications have completed. Its result is the empty string. 🧚

`::ldap::modifyMulti` ✨

::ldap::modifyMulti handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?

Same deal as above — this modifies the object dn on the ldap server you're connected to via handle. Replaces attributes with new values, deletes attributes, adds new attributes with new values. 🌈

The difference: all arguments are lists with the format:

attr1 {val11 val12 ...} attr2 {val21...} ...

where each value list may be empty, which is how you delete all attributes. The optional arguments default to empty lists of attributes to delete and to add. 🎀

list attrValToReplace (in) — no attributes will be changed if this argument is empty. The dictionary contains the new attributes and their values. They replace all attributes known to the object. 👑
list attrToDelete (in) — no attributes will be deleted if this argument is empty. If no value is specified, the whole set of values for an attribute will be deleted. 💀
list attrValToAdd (in) — no attributes will be added if this argument is empty. ✨

The command blocks until all modifications have completed. Its result is the empty string. 💖

`::ldap::add` 🎀

::ldap::add handle dn attrValueTuples

This creates a new object using the specified dn. The attributes of the new object get set to the values in the list attrValueTuples. 🌸

Multiple valuated attributes may be specified using multiple tuples. The command blocks until the operation has completed. Its result is the empty string. ✨

`::ldap::addMulti` 👑

::ldap::addMulti handle dn attrValueTuples

This one is the preferred way to create a new object using the specified dn. 💅 The attributes of the new object get set to the values in the dictionary attrValueTuples (which is keyed by the attribute names). Each tuple is a list containing multiple values. 🦋

The command blocks until the operation has completed. Its result is the empty string. 🌈

`::ldap::delete` 💀

::ldap::delete handle dn

This removes the object specified by dn, and all its attributes, from the server. Gone. Poof. ✨

The command blocks until the operation has completed. Its result is the empty string. 🧚

`::ldap::modifyDN` 🔥

::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?

This moves or copies the object specified by dn to a new location in the tree of objects. That new location is specified by newrdn — a relative designation — or by newrdn and newSuperior, which together make an absolute designation. 🌳

The optional argument deleteOld defaults to true, i.e. a move operation. If deleteOld is not set, then the operation creates a copy of dn in the new location. 🙈

The optional argument newSuperior defaults to an empty string, meaning the object must not be relocated into another branch of the tree. If this argument is given, the argument deleteOld must be specified as well. ⚠️

The command blocks until the operation has completed. Its result is the empty string. 💖

`::ldap::info` ✨ — the whole little family

::ldap::info ip handle

Returns the IP address of the remote LDAP server the handle is connected to. 📍

::ldap::info bound handle

Returns 1 if a handle has successfully completed a ::ldap::bind. If no bind was done, or it failed, a 0 comes back. 🎀

::ldap::info bounduser handle

Returns the username used in the bind operation, if a handle has successfully completed a ::ldap::bind. If no bound was done or it failed, an empty string comes back. 👑

::ldap::info connections

Returns all currently existing ldap connection handles. 🌈

::ldap::info tls handle

Returns 1 if the ldap connection handle used TLS/SSL for the connection via ldap::secure_connect or completed ldap::starttls, and 0 otherwise. 🔒

::ldap::info tlsstatus handle

Returns the current security status of a TLS secured channel. The result is a list of key-value pairs describing the connected peer (peep the TLS package documentation for the returned values). If the connection isn't secured with TLS, an empty list comes back. 🦋

::ldap::info saslmechanisms handle

Returns the supported SASL mechanisms advertised by the server. Only valid in a bound state (anonymous or other). ✨

::ldap::info control handle

Returns the supported controls advertised by the server, as a list of OIDs. Only valid in a bound state.

This is currently experimental and subject to change. ⚠️

::ldap::info extensions extensions

Returns the supported LDAP extensions as a list of OIDs. Only valid in a bound state.

This is currently experimental and subject to change. ⚠️

::ldap::info whoami handle

Returns the authzId for the current connection. This implements the RFC 4532 protocol extension. 💅

✨ EXAMPLES ✨

okay bestie, first up: a small example, extracted from the test application coming with this code. it's giving connect, bind, add, modify, modify, modify, modifyDN, delete, unbind, disconnect and honestly? iconic. here's the exact code, no cap:

                  package require ldap

                  # Connect, bind, add a new object, modify it in various ways

                  set handle [ldap::connect localhost 9009]

                  set dn "cn=Manager, o=University of Michigan, c=US"
                  set pw secret

                  ldap::bind $handle $dn $pw

                  set dn "cn=Test User,ou=People,o=University of Michigan,c=US"

                  ldap::add $handle $dn {
                objectClass     OpenLDAPperson
                cn              {Test User}
                mail            test.user@google.com
                uid             testuid
                sn              User
                telephoneNumber +31415926535
                telephoneNumber +27182818285
                  }

                  set dn "cn=Another User,ou=People,o=University of Michigan,c=US"

                  ldap::addMulti $handle $dn {
                objectClass     {OpenLDAPperson}
                cn              {{Anotther User}}
                mail            {test.user@google.com}
                uid             {testuid}
                sn              {User}
                telephoneNumber {+31415926535 +27182818285}
                  }

                  # Replace all attributes
                  ldap::modify $handle $dn [list drink icetea uid JOLO]

                  # Add some more
                  ldap::modify $handle $dn {} {} [list drink water  drink orangeJuice pager "+1 313 555 7671"]

                  # Delete
                  ldap::modify $handle $dn {} [list drink water  pager ""]

                  # Move
                  ldap::modifyDN $handle $dn "cn=Tester"

                  # Kill the test object, and shut the connection down.
                  set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
                  ldap::delete $handle $dn

                  ldap::unbind     $handle
                  ldap::disconnect $handle

and another example, a simple query, and processing the results. this one is lowkey a whole vibe: connect, bind, search, then loop through the results and format them like parray would. the code is literally right here:

                  package require ldap
                  set handle [ldap::connect ldap.acme.com 389]
                  ldap::bind $handle
                  set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
                  foreach result $results {
                foreach {object attributes} $result break

                # The processing here is similar to what 'parray' does.
                # I.e. finding the longest attribute name and then
                # generating properly aligned output listing all attributes
                # and their values.

                set width 0
                set sortedAttribs {}
                foreach {type values} $attributes {
                    if {[string length $type] > $width} {
                   set width [string length $type]
                    }
                    lappend sortedAttribs [list $type $values]
                }

                puts "object='$object'"

                foreach sortedAttrib  $sortedAttribs {
                    foreach {type values} $sortedAttrib break
                    foreach value $values {
                   regsub -all "\[\x01-\x1f\]" $value ? value
                   puts [format "  %-${width}s %s" $type $value]
                    }
                }
                puts ""
                  }
                  ldap::unbind $handle
                  ldap::disconnect $handle

🐛 BUGS, IDEAS, FEEDBACK 🐛

bestie, real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. not a maybe, it's a definitely. please report such in the category ldap of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. also please report any ideas for enhancements you may have for either package and/or documentation. we love a glow-up idea. 💅

when proposing code changes, please provide unified diffs, i.e the output of diff -u. no messy vibes.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. that's the move. 🫶

🔑 KEYWORDS 🔑

the keywords are giving:

directory access
internet
ldap
ldap client
protocol
rfc 2251
rfc 4511
x.500

🗂️ CATEGORY 🗂️

Networking. periodt.

and that's the whole page, bestie. footer check: tcllib version 1.10.2, page ldap(n). no date on this footer, so we're not making one up. slay. 💅✨

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

ldap(n)

ldap(n) — the LDAP client, bestie edition 💅

✨ NAME ✨

🌸 SYNOPSIS 🌸

💖 DESCRIPTION 💖

🔐 TLS SECURITY CONSIDERATIONS 🔐

🫶 COMMANDS 🫶

::ldap::connect host ?port?

::ldap::tlsoptions reset

::ldap::tlsoptions ?opt1 val1? ?opt2 val2? ...

::ldap::secure_connect host ?port?

::ldap::secure_connect host ?port? ?verify_cert? ?sni_servername?

::ldap::disconnect handle

::ldap::starttls handle

::ldap::starttls handle ?cafile? ?certfile? ?keyfile? ?verify_cert? ?sni_servername?

::ldap::bind handle ?name? ?password?

::ldap::bindSASL handle ?name? ?password?

::ldap::unbind handle

::ldap::search handle baseObject filterString attributes options

::ldap::searchInit 💅

::ldap::searchNext ✨

::ldap::searchEnd 🌸

::ldap::modify 💅

::ldap::modifyMulti ✨

::ldap::add 🎀

::ldap::addMulti 👑

::ldap::delete 💀

::ldap::modifyDN 🔥

::ldap::info ✨ — the whole little family