git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-tcl.5

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