git.sur5r.net Git - openldap/blob - servers/slapd/back-tcl/README.back-tcl

   1 Tcl Backend Interface for OpenLDAP
   2
   3
   4 ----------------------------
   5 Synopsis of slapd.conf setup
   6 ----------------------------
   7
   8 database        tcl
   9 suffix          o=Suffix
  10
  11 # The full path to the tcl script used for this database
  12 scriptpath      /usr/lib/ldap/database.tcl
  13
  14 # The procs for each ldap function. This similar to how
  15 # the shell backend setup works, but these refer to
  16 # the tcl procs in the 'scriptpath' script that handle them
  17 search          <proc>
  18 add             <proc>
  19 delete          <proc>
  20 modify          <proc>
  21 bind            <proc>
  22 unbind          <proc>
  23 modrdn          <proc>
  24 compare         <proc>
  25 abandon         <proc>
  26
  27 # This is one of the biggest pluses of using the tcl backend.
  28 # The realm let's you group several databases to the same interpretor.
  29 # This basically means they share the same global variables and proc
  30 # space. So global variables, as well as all the procs are callable
  31 # between databases. If no tclrealm is specified, it is put into the
  32 # "default" realm.
  33 tclrealm        <interpretor name>
  34
  35
  36 -----------------------------------------
  37 Synopsis of variables passed to the procs
  38 -----------------------------------------
  39
  40 abandon { action msgid suffix }
  41
  42         action - Always equal to ABANDON
  43         msgid  - The msgid of this ldap session
  44         suffix - List of suffix(es) associated with the call. Each one is
  45                  and entry in a tcl formatted list (surrounded by {}'s)
  46
  47 add { action msgid suffix entry }
  48
  49         action - Always equal to ADD
  50         msgid  - The msgid of this ldap session
  51         suffix - List of suffix(es) associated with the call. Each one is
  52                  and entry in a tcl formatted list (surrounded by {}'s)
  53         entry  - Full entry to add. Each "type: val" is an element in a
  54                  tcl formatted list.
  55
  56 bind { action msgid suffix dn method cred_len cred }
  57
  58         action   - Always equal to BIND
  59         msgid    - The msgid of this ldap session
  60         suffix   - List of suffix(es) associated with the call. Each one
  61                    is and entry in a tcl formatted list (surrounded by {}'s)
  62         dn       - DN being bound to
  63         method   - One of the ldap authentication methods
  64         cred_len - Length of cred
  65         cred     - Credentials being used to authenticate, according to
  66                    RFC, if this value is empty, then it should be
  67                    considered an anonomous bind (??)
  68
  69 compare { action msgid suffix dn ava_type ava_value }
  70
  71         action    - Always equal to COMPARE
  72         msgid     - The msgid of this ldap session
  73         suffix    - List of suffix(es) associated with the call. Each one
  74                     is and entry in a tcl formatted list (surrounded by {}'s)
  75         dn        - DN for compare
  76         ava_type  - Type for comparison
  77         ava_value - Value to compare
  78
  79 delete { action msgid suffix dn }
  80
  81         action    - Always equal to DELETE
  82         msgid     - The msgid of this ldap session
  83         suffix    - List of suffix(es) associated with the call. Each one
  84                     is and entry in a tcl formatted list (surrounded by {}'s)
  85         dn        - DN to delete
  86
  87 modify { action msgid suffix dn mods }
  88
  89         action - Always equal to MODIFY
  90         msgid  - The msgid of this ldap session
  91         suffix - List of suffix(es) associated with the call. Each one
  92                  is and entry in a tcl formatted list (surrounded by {}'s)
  93         dn     - DN to modify
  94         mods   - Tcl list of modifications. List is formatted in this way:
  95
  96                  {
  97                    { {op: type} {type: val} }
  98                    { {op: type} {type: val} {type: val} }
  99                    ...
 100                  }
 101
 102                  Newlines are not present in the actual var, they are
 103                  present here for clarification. "op" is the type of
 104                  modification (add, delete, replace).
 105
 106 modrdn { action msgid suffix dn newrdn deleteoldrdn }
 107
 108         action - Always equal to MODRDN
 109         msgid  - The msgid of this ldap session
 110         suffix - List of suffix(es) associated with the call. Each one
 111                  is and entry in a tcl formatted list (surrounded by {}'s)
 112         dn     - DN who's RDN is being renamed
 113         newrdn - New RDN
 114         deleteoldrdn - Boolean stating whether or not the old RDN should
 115                  be removed after being renamed
 116
 117 search { action msgid suffix base scope deref sizelimit timelimit
 118          filterstr attrsonly attrlist }
 119
 120         action - Always equal to SEARCH
 121         msgid  - The msgid of this ldap session
 122         suffix - List of suffix(es) associated with the call. Each one
 123                  is and entry in a tcl formatted list (surrounded by {}'s)
 124         base   - Base for this search
 125         scope  - Scope of search, ( 0 | 1 | 2 )
 126         deref  - Alias dereferencing ( 0 | 1 | 2 | 3 )
 127         sizelimit - Script should try not to return more data that this
 128         timelimit - Time limit for search
 129         filterstr - Filter string as sent by the requestor.
 130         attrsonly - Boolean for whether to list only the attributes
 131                  instead of attributes and their values.
 132         attrlist  - Tcl list if to retrieve.
 133
 134 unbind { action msgid suffix dn }
 135
 136         action - Always equal to UNBIND
 137         msgid  - The msgid of this ldap session
 138         suffix - List of suffix(es) associated with the call. Each one
 139                  is and entry in a tcl formatted list (surrounded by {}'s)
 140         dn     - DN to unbind
 141
 142
 143 ------------------------------------
 144 Synopsis of Return Method and Syntax
 145 ------------------------------------
 146
 147 There are only 2 return types. All procs must return a result to show
 148 status of the operation. The result is in this form:
 149
 150   { RESULT {code: <integer>} {matched: <partialdn>} {info: <string>} {} }
 151
 152 This is best accomplished with this type of tcl code
 153
 154   lappend ret_val "RESULT"
 155   lappend ret_val "code: 0"
 156   lappend ret_val ""
 157   return $ret_val
 158
 159 The final empty string (item in list) is neccesary to point to the end of
 160 list. The 'code', 'matched', and 'info' values are not neccesary, and
 161 default values are given if not specified. The 'code' value is usually an
 162 LDAP error in decimal notation from ldap.h. The 'info', may be sent back
 163 to the client, depending on the function. LDAP uses the value of 'code' to
 164 indicate whether or not the authentication is acceptible in the bind proc.
 165
 166 The other type of return is for searches. It is similar format to the
 167 shell backend return (as is most of the syntax here). It's format follows:
 168
 169     {dn: o=Company, c=US} {attr: val} {objectclass: val} {}
 170     {dn: o=CompanyB, c=US} {attr: val} {objectclass: val} {}
 171
 172 Again, newlines are for visual purposes here. Also note the {} marking the
 173 end of the entry (same affect as a newline in ldif format). Here is some
 174 example code again, showing a full search proc example.
 175
 176 # Note that 'args' let's you lump all possible args into one var, used
 177 # here for simplicity of exmaple
 178 proc ldap:search { args } {
 179   # perform some operations
 180
 181   lappend ret_val "dn: $rdn,$base"
 182   lappend ret_val "objectclass: $objcl"
 183   lappend ret_val "sn: $rdn"
 184   lappend ret_val "mail: $email"
 185   lappend ret_val ""
 186 # Now setup the result
 187   lappend ret_val "RESULT"
 188   lappend ret_val "code: 0"
 189   lappend ret_val ""
 190
 191   return $ret_val
 192 }
 193
 194 NOTE: Newlines in the return value is acceptible in search entries (ie.
 195 when returning base64 encoded binary entries).
 196
 197
 198 -------------------------------------
 199 Synopsis of Builtin Commands and Vars
 200 -------------------------------------
 201
 202 ldap:debug <msg>
 203
 204   Allows you to send debug messages through OpenLDAP's native debuging
 205   system, this is sent as a LDAP_DEBUG_ANY and will be logged. Useful for
 206   debugging scripts or logging bind failures.