Provided by: slapd_2.2.26-5ubuntu2_i386 bug

NAME

       slapd-tcl - Tcl backend to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

DESCRIPTION

       The  Tcl backend to slapd(8) works by embedding a Tcl(3tcl) interpreter
       into slapd(8).  Any tcl database  section  of  the  configuration  file
       slapd.conf(5) must then specify what Tcl script to use.

       This backend is experimental.

WARNING

       This  backends  calling  conventions  have changed since OpenLDAP 2.0.
       Previously, the 2nd argument to the procs was a message ID.   Now  they
       are  an  "operation  ID"  string.   Also,  proc  abandon now gets a new
       abandonid argument.

CONFIGURATION

       These slapd.conf options apply to the TCL backend database.   That  is,
       they  must  follow a "database tcl" line and come before any subsequent
       "backend" or "database" lines.  Other database options are described in
       the slapd.conf(5) manual page.

       scriptpath <filename.tcl>
              The full path to the tcl script used for this database.

       search <proc>
       add <proc>
       delete <proc>
       modify <proc>
       bind <proc>
       unbind <proc>
       modrdn <proc>
       compare <proc>
       abandon <proc>
              The  procs  for each ldap function.  They refer to the tcl procs
              in the ‘scriptpath’ script that handles them.

       tclrealm <interpreter name>
              This is one of the biggest pluses of using the tcl backend.  The
              realm  lets you group several databases to the same interpreter.
              This basically means they share the same  global  variables  and
              proc  space.  So global variables, as well as all the procs, are
              callable between databases.  If no tclrealm is specified, it  is
              put into the "default" realm.

Variables passed to the procs

       abandon { action opid suffix abandonid }
              action    - Always equal to ABANDON.
              opid      - The opid of this ldap operation.
              suffix    - List of suffix(es) associated with the
                          call.  Each one is an entry in a tcl
                          formatted list (surrounded by {}’s).
              abandonid - The opid of the operation to abandon.

       add { action opid suffix entry }
              action - Always equal to ADD.
              opid   - The opid of this ldap operation.
              suffix - List of suffix(es), as above.
              entry  - Full entry to add. Each "type: val" is
                       an element in a tcl formatted list.

       bind { action opid suffix dn method cred_len cred }
              action   - Always equal to BIND.
              opid     - The opid of this ldap operation.
              suffix   - List of suffix(es), as above.
              dn       - DN being bound to.
              method   - One of the ldap authentication methods.
              cred_len - Length of cred.
              cred     - Credentials being used to authenticate,
                         according to RFC.  If this value is empty,
                         then it should be considered an anonymous
                         bind (??)

       compare { action opid suffix dn ava_type ava_value }
              action    - Always equal to COMPARE.
              opid      - The opid of this ldap operation.
              suffix    - List of suffix(es), as above.
              dn        - DN for compare.
              ava_type  - Type for comparison.
              ava_value - Value to compare.

       delete { action opid suffix dn }
              action    - Always equal to DELETE.
              opid      - The opid of this ldap operation.
              suffix    - List of suffix(es), as above.
              dn        - DN to delete.

       modify { action opid suffix dn mods }
              action - Always equal to MODIFY.
              opid   - The opid of this ldap operation.
              suffix - List of suffix(es), as above.
              dn     - DN to modify.
              mods   - Tcl list of modifications.
                       The list is formatted in this way:

                       {
                         { {op: type} {type: val} }
                         { {op: type} {type: val} {type: val} }
                         ...
                       }

                       Newlines are not present in the actual var,
                       they are present here for clarification.
                       "op" is the type of modification
                       (ADD, DELETE, REPLACE).

       modrdn { action opid suffix dn newrdn deleteoldrdn }
              action - Always equal to MODRDN.
              opid   - The opid of this ldap operation.
              suffix - List of suffix(es), as above.
              dn     - DN whose RDN is being renamed.
              newrdn - New RDN.
              deleteoldrdn - Boolean stating whether or not the
                       old RDN should be removed after being renamed.

       search  {  action  opid  suffix  base  scope  deref sizelimit timelimit
       filterstr attrsonly attrlist }
              action    - Always equal to SEARCH.
              opid      - The opid of this ldap operation.
              suffix    - List of suffix(es), as above.
              base      - Base for this search.
              scope     - Scope of search, ( 0 | 1 | 2 ).
              deref     - Alias dereferencing ( 0 | 1 | 2 | 3 ).
              sizelimit - Maximum number of entries to return.
              timelimit - Time limit for search.
              filterstr - Filter string as sent by the requester.
              attrsonly - Boolean for whether to list only the
                          attributes, and not values as well.
              attrlist  - Tcl list if to retrieve.

       unbind { action opid suffix dn }
              action - Always equal to UNBIND.
              opid   - The opid of this ldap operation.
              suffix - List of suffix(es), as above.
              dn     - DN to unbind.

       An   opid  (operation  ID)  is  a  "connection  ID/message  ID"  string
       identifying an operation.

Return Method and Syntax

       There are only 2 return types.  All procs must return a result to  show
       status of the operation.  The result is in this form:

              { RESULT {code: <integer>} {matched: <partialdn>}
                {info: <string>} {} }

       This is best accomplished with this type of tcl code

                lappend ret_val "RESULT"
                lappend ret_val "code: 0"
                lappend ret_val ""
                return $ret_val

       The  final empty string (item in list) is necessary to point to the end
       of list.  The ‘code’, ‘matched’, and ‘info’ values are  not  necessary,
       and  default  values  are  given if not specified.  The ‘code’ value is
       usually an LDAP error in decimal notation from ldap.h.  The ‘info’, may
       be  sent  back  to  the client, depending on the function.  In the bind
       proc, LDAP uses the value of ‘code’ to  indicate  whether  or  not  the
       authentication is acceptable.

       The  other type of return is for searches.  It is similar format to the
       shell backend return (as is most  of  the  syntax  here).   Its  format
       follows:

              {dn: o=Company, c=US} {attr: val} {objectclass: val} {}
              {dn: o=CompanyB, c=US} {attr: val} {objectclass: val} {}

       Again, newlines are for visual purposes here.  Also note the {} marking
       the end of the entry (same effect as a newline in ldif  format).   Here
       is some example code again, showing a full search proc example.

              # Note that ‘args’ lets you lump all possible args
              # into one var, used here for simplicity of example
              proc ldap:search { args } {
                # ...perform some operations...

                lappend ret_val "dn: $rdn,$base"
                lappend ret_val "objectclass: $objcl"
                lappend ret_val "sn: $rdn"
                lappend ret_val "mail: $email"
                lappend ret_val ""
                # Now setup the result
                lappend ret_val "RESULT"
                lappend ret_val "code: 0"
                lappend ret_val ""
                return $ret_val
              }

       NOTE:  Newlines  in  the  return  value is acceptable in search entries
       (i.e. when returning base64 encoded binary entries).

Builtin Commands and Variables

       ldap:debug <msg>
              Allows you to send  debug  messages  through  OpenLDAP’s  native
              debugging  system,  this is sent as a LDAP_DEBUG_ANY and will be
              logged.  Useful for debugging scripts or logging bind  failures.

FILES

       /etc/ldap/slapd.conf
              default slapd configuration file

SEE ALSO

       slapd.conf(5), slapd(8), Tcl(3tcl).